openapi: 3.1.0
info:
  title: Stackr API
  version: 0.1.0
servers:
  - url: https://stackr.grasany.com
security:
  - DeployToken: []
paths:
  /api/projects/{projectId}/native-recovery/operations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerNativeServiceOperations
      security: [{ OwnerSession: [] }]
      description: Read a version-2 page of at most 20 retained SQL/KV operation records ordered by createdAt and operationId descending. Each row has a recorded, unrecorded or not_applicable quota reservation summary; reservationHistoryComplete remains false. Only records with the captured original owner, identity and current authorization epoch are disclosed. Current owner session/account/pilot/configuration checks and final revision/epoch/clock fences apply after inspection finalization. Provider activation and usage-billing enrollment are not required for this inspection. Accepts one optional cursor and rejects all other query parameters. Uses one shared usage-inspection unit; only inspection accounting can be written. No provider is queried and no native hold, resource, token, manifest or usage counter changes. Source-current flags are stored SQL comparisons, not live session/invite/configuration or provider verification. Legacy holds receive no retroactive journal or quota receipts.
      parameters:
        - in: query
          name: cursor
          description: Pass the previous page's cursor unchanged to read older records. Only one cursor is accepted; an omitted cursor starts with the newest records.
          schema: { type: string, maxLength: 54, pattern: '^(0|[1-9][0-9]{0,15})_([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$' }
      responses:
        '200': { $ref: '#/components/responses/NativeServiceOperations' }
        '400': { description: Invalid or duplicate cursor, or unsupported query parameter }
        '401': { description: Current owner session required; bearer substitution rejected }
        '403': { description: Invalid browser origin or cross-site request }
        '404': { description: Project or current owner authorization unavailable }
        '409': { description: Inspection lease or final revision/epoch/clock fence changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded operation metadata or inspection admission unavailable; malformed or over-limit evidence fails closed }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/operator/native-recovery/{projectId}/operations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOperatorNativeServiceOperations
      security: [{ NativeRecoveryOperatorToken: [] }]
      description: Audit the target project's retained SQL/KV operation records across original owners and epochs. The version-2 response includes redacted operation-bound quota receipt summaries, never private prior/after counters, shared totals, applied limits or credential hashes; reservationHistoryComplete remains false. Uses the existing distinct native-recovery operator bearer at the exact canonical HTTPS origin without Cookie or Origin headers. Audit does not establish owner consent or grant provider/recovery authority. Returns at most 20 records with a bounded sentinel and optional cursor, ordered by createdAt and operationId descending. Only one cursor query parameter is accepted. Reserves one shared usage-inspection unit and rechecks credential/configuration and metadata/epoch/clock fences after inspection finalization. No provider or native-service mutation occurs. Late acknowledgements remain attached to their original record even when its stored source/authority flags are false; they never authorize a new RPC or hold release.
      parameters:
        - in: query
          name: cursor
          description: Pass the previous page's cursor unchanged to read older records. Only one cursor is accepted.
          schema: { type: string, maxLength: 54, pattern: '^(0|[1-9][0-9]{0,15})_([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$' }
      responses:
        '200': { $ref: '#/components/responses/NativeServiceOperations' }
        '400': { description: Invalid or duplicate cursor, or unsupported query parameter }
        '401': { description: Valid separate native-recovery operator bearer required; Cookie and Origin headers rejected }
        '404': { description: Operator channel disabled, noncanonical origin, project unavailable or authorization changed }
        '409': { description: Inspection lease or final revision/epoch/clock fence changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded operation metadata or inspection admission unavailable; malformed or over-limit evidence fails closed }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/projects/{projectId}/native-recovery:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerNativeRecoverySnapshot
      security: [{ OwnerSession: [] }]
      description: Inspect redacted native SQL/KV recovery metadata with the current owner session. Bearer substitution and query parameters are rejected. Fresh session/account/pilot/identity/access-epoch checks and metadata/finite-lease clock fences precede disclosure. Reserves one shared usage-inspection unit. No provider is queried and no native resource, hold, token, manifest or usage counter is changed; inspection admission and observations can be written. A hold establishes neither dispatch nor finality.
      responses:
        '200': { $ref: '#/components/responses/NativeRecoverySnapshot' }
        '400': { description: Query parameters are unsupported }
        '401': { description: Current owner session required; bearer substitution rejected }
        '403': { description: Invalid browser origin or cross-site request }
        '404': { description: Project or current owner authorization unavailable }
        '409': { description: Inspection lease, metadata revision, access epoch or finite-lease clock transition changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded recovery metadata or inspection admission unavailable }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/projects/{projectId}/native-recovery/export:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportOwnerNativeRecoverySnapshot
      security: [{ OwnerSession: [] }]
      description: Download the same owner-authorized metadata as a canonical private export. Uses one shared usage-inspection unit and the same fresh authorization and final evidence fences as snapshot inspection. Rejects query parameters and bearer substitution. Its SHA-256 content binding is unsigned and does not authenticate an issuer, provider evidence or approval. No provider or native-service mutation occurs.
      responses:
        '200': { $ref: '#/components/responses/NativeRecoveryExport' }
        '400': { description: Query parameters are unsupported }
        '401': { description: Current owner session required; bearer substitution rejected }
        '403': { description: Invalid browser origin or cross-site request }
        '404': { description: Project or current owner authorization unavailable }
        '409': { description: Inspection lease or final evidence/clock fence changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded recovery metadata or inspection admission unavailable }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/operator/native-recovery/{projectId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOperatorNativeRecoverySnapshot
      security: [{ NativeRecoveryOperatorToken: [] }]
      description: Audit existing project recovery metadata at the exact canonical HTTPS origin with the distinct native-recovery operator bearer, without Cookie or Origin headers. An existing suspended owner's project can be audited without establishing owner consent. Query parameters are rejected. Uses one shared operator usage-inspection unit with credential rotation and final metadata/access-epoch/clock checks. No provider is queried and native resources, holds, tokens, manifests and usage counters remain unchanged; inspection admission/observations can be written.
      responses:
        '200': { $ref: '#/components/responses/NativeRecoverySnapshot' }
        '400': { description: Query parameters are unsupported }
        '401': { description: Valid separate native-recovery operator bearer required; Cookie and Origin headers rejected }
        '404': { description: Operator channel disabled, noncanonical origin, project unavailable or authorization changed }
        '409': { description: Inspection lease or final evidence/clock fence changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded recovery metadata or inspection admission unavailable }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/operator/native-recovery/{projectId}/export:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportOperatorNativeRecoverySnapshot
      security: [{ NativeRecoveryOperatorToken: [] }]
      description: Download canonical recovery metadata under the same separate operator bearer, canonical-origin and no-Cookie/no-Origin restrictions as operator inspection. Query parameters are rejected. Uses one shared usage-inspection unit and fresh final authorization/evidence fences. The unsigned content digest grants no issuer, provider, approval or execution authority. No provider or native-service mutation occurs.
      responses:
        '200': { $ref: '#/components/responses/NativeRecoveryExport' }
        '400': { description: Query parameters are unsupported }
        '401': { description: Valid separate native-recovery operator bearer required; Cookie and Origin headers rejected }
        '404': { description: Operator channel disabled, noncanonical origin, project unavailable or authorization changed }
        '409': { description: Inspection lease or final evidence/clock fence changed; inspect again }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded recovery metadata or inspection admission unavailable }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/operator/native-recovery/{projectId}/check:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: checkOperatorNativeRecoveryReview
      security: [{ NativeRecoveryOperatorToken: [] }]
      description: Compare the direct unsigned review packet with a fresh SQL/KV metadata snapshot. Uses the separate native-recovery operator bearer at the exact canonical HTTPS origin without Cookie or Origin headers; query parameters are rejected. The packet and snapshot must remain within 60 seconds of their original observations for a current assessment. Body JSON is bounded to 16384 bytes, depth 8 and 2048 structural tokens with a five-second read deadline. Reserves one nonrefundable shared usage-inspection unit before body validation. HTTP 200 can describe either current or stale metadata; a current result grants no approval, release, correction, refund, provider action or billing authority and noInterveningWorkVerified remains false. After inspection finalization, authorization/configuration, metadata revision/access epoch, finite-lease transitions and current-review expiry are checked again before disclosure. Those finalization reads fall outside incomplete inspection observations, which never establish provider usage or billing. No provider is queried and native service state/usage remains unchanged; inspection admission/observations can be written.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NativeRecoveryReview' }
      responses:
        '200': { $ref: '#/components/responses/NativeRecoveryAssessment' }
        '400': { description: Invalid review, cross-project packet, query parameters, JSON, UTF-8, length or structure }
        '401': { description: Valid separate native-recovery operator bearer required; Cookie and Origin headers rejected }
        '404': { description: Operator channel disabled, noncanonical origin, project unavailable or authorization changed }
        '408': { description: Request body aborted or its five-second deadline exceeded }
        '409': { description: Final inspection/evidence/authorization/finite-lease clock fence changed, or a current assessment expired before disclosure; inspect again }
        '413': { description: Review body exceeds 16384 bytes }
        '429': { $ref: '#/components/responses/NativeRecoveryInspectionLimited' }
        '503': { description: Complete bounded recovery metadata or inspection admission unavailable }
        '504': { description: Inspection exceeded its 20-second workflow deadline }
  /api/projects/{projectId}/service-usage:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerNativeServiceUsage
      security:
      - OwnerSession: []
      description: Requires the current project-owner workspace session. File, SQL, queue, data and operator bearer credentials do not establish this owner channel. Fresh
        session/account/pilot policy and SQL ownership are checked before data return. Both report and export reserve one usage inspection unit before payload SQL, share
        the existing owner/operator inspection limits and retain reservations on failure. Initial auth/admission, finalization and late activity may be outside statement
        observations. No provider is queried; inspection admission/observation metadata can be written while resource state and provider data remain unchanged. No query
        parameters are accepted. Separate monthly/daily/inventory windows and latest-source-only counter coverage must not be treated as one complete billing period.
      responses:
        '200':
          description: Private native-service usage/capacity metadata
          headers:
            Cache-Control:
              schema:
                type: string
                pattern: private.*no-store
              description: Uncacheable private metadata.
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                const: 1
              description: Fixed usage-inspection work reservation, not monetary cost or provider rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NativeServiceUsageReport'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Current owner session required; bearer substitution rejected
        '404':
          description: Project/current owner authorization unavailable
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: Inspection request/unit/slot capacity exhausted. Retry-After 30 is a retry hint, not a guarantee; daily limits reset on SQL UTC date.
          headers:
            Retry-After:
              schema:
                type: string
                const: '30'
        '503':
          description: Admission, schema or complete bounded service metadata unavailable
        '504':
          description: Inspection work exceeded its 20-second deadline
        '403':
          description: Invalid browser request origin or cross-site metadata request
        '405':
          description: Only GET is supported
          headers:
            Allow:
              schema:
                const: GET
  /api/projects/{projectId}/service-usage/export:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportOwnerNativeServiceUsage
      security:
      - OwnerSession: []
      description: Requires the current project-owner workspace session. File, SQL, queue, data and operator bearer credentials do not establish this owner channel. Fresh
        session/account/pilot policy and SQL ownership are checked before data return. Both report and export reserve one usage inspection unit before payload SQL, share
        the existing owner/operator inspection limits and retain reservations on failure. Initial auth/admission, finalization and late activity may be outside statement
        observations. No provider is queried; inspection admission/observation metadata can be written while resource state and provider data remain unchanged. No query
        parameters are accepted. Separate monthly/daily/inventory windows and latest-source-only counter coverage must not be treated as one complete billing period.
      responses:
        '200':
          description: Private versioned native-service metadata export
          headers:
            Cache-Control:
              schema:
                type: string
                pattern: private.*no-store
              description: Uncacheable private metadata.
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                const: 1
              description: Fixed usage-inspection work reservation, not monetary cost or provider rows.
            Content-Disposition:
              schema:
                type: string
                pattern: ^attachment; filename="stackr-service-usage-\d{4}-\d{2}-\d{2}\.json"$
              description: Fixed date-based filename; no private identifier is placed in the filename.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NativeServiceUsageExport'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Current owner session required; bearer substitution rejected
        '404':
          description: Project/current owner authorization unavailable
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: Inspection request/unit/slot capacity exhausted. Retry-After 30 is a retry hint, not a guarantee; daily limits reset on SQL UTC date.
          headers:
            Retry-After:
              schema:
                type: string
                const: '30'
        '503':
          description: Admission, schema or complete bounded service metadata unavailable
        '504':
          description: Inspection work exceeded its 20-second deadline
        '403':
          description: Invalid browser request origin or cross-site metadata request
        '405':
          description: Only GET is supported
          headers:
            Allow:
              schema:
                const: GET
  /api/operator/service-usage/{projectId}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOperatorNativeServiceUsage
      security:
      - ServiceUsageOperatorToken: []
      description: Requires a distinct STACKR_SERVICE_USAGE_OPERATOR_TOKEN of 43–128 base64url characters at the exact canonical HTTPS origin, without Cookie or Origin headers.
        The object-storage operator credential is not reused. Explicit operator audit can view an existing suspended owner project without impersonating owner consent. Both
        report and export reserve one usage inspection unit before payload SQL, share the existing owner/operator inspection limits and retain reservations on failure. Initial
        auth/admission, finalization and late activity may be outside statement observations. No provider is queried; inspection admission/observation metadata can be written
        while resource state and provider data remain unchanged. No query parameters are accepted. Separate monthly/daily/inventory windows and latest-source-only counter
        coverage must not be treated as one complete billing period.
      responses:
        '200':
          description: Private native-service usage/capacity metadata
          headers:
            Cache-Control:
              schema:
                type: string
                pattern: private.*no-store
              description: Uncacheable private metadata.
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                const: 1
              description: Fixed usage-inspection work reservation, not monetary cost or provider rows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NativeServiceUsageReport'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Separate service-usage operator bearer required; browser credentials rejected
        '404':
          description: Project or canonical operator configuration unavailable; unsupported method
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: Inspection request/unit/slot capacity exhausted. Retry-After 30 is a retry hint, not a guarantee; daily limits reset on SQL UTC date.
          headers:
            Retry-After:
              schema:
                type: string
                const: '30'
        '503':
          description: Admission, schema or complete bounded service metadata unavailable
        '504':
          description: Inspection work exceeded its 20-second deadline
  /api/operator/service-usage/{projectId}/export:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportOperatorNativeServiceUsage
      security:
      - ServiceUsageOperatorToken: []
      description: Requires a distinct STACKR_SERVICE_USAGE_OPERATOR_TOKEN of 43–128 base64url characters at the exact canonical HTTPS origin, without Cookie or Origin headers.
        The object-storage operator credential is not reused. Explicit operator audit can view an existing suspended owner project without impersonating owner consent. Both
        report and export reserve one usage inspection unit before payload SQL, share the existing owner/operator inspection limits and retain reservations on failure. Initial
        auth/admission, finalization and late activity may be outside statement observations. No provider is queried; inspection admission/observation metadata can be written
        while resource state and provider data remain unchanged. No query parameters are accepted. Separate monthly/daily/inventory windows and latest-source-only counter
        coverage must not be treated as one complete billing period.
      responses:
        '200':
          description: Private versioned native-service metadata export
          headers:
            Cache-Control:
              schema:
                type: string
                pattern: private.*no-store
              description: Uncacheable private metadata.
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                const: 1
              description: Fixed usage-inspection work reservation, not monetary cost or provider rows.
            Content-Disposition:
              schema:
                type: string
                pattern: ^attachment; filename="stackr-service-usage-\d{4}-\d{2}-\d{2}\.json"$
              description: Fixed date-based filename; no private identifier is placed in the filename.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NativeServiceUsageExport'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Separate service-usage operator bearer required; browser credentials rejected
        '404':
          description: Project or canonical operator configuration unavailable; unsupported method
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: Inspection request/unit/slot capacity exhausted. Retry-After 30 is a retry hint, not a guarantee; daily limits reset on SQL UTC date.
          headers:
            Retry-After:
              schema:
                type: string
                const: '30'
        '503':
          description: Admission, schema or complete bounded service metadata unavailable
        '504':
          description: Inspection work exceeded its 20-second deadline
  /api/projects/{projectId}/files/usage:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerStorageControlUsage
      security:
      - OwnerSession: []
      description: 'Requires the project owner workspace session; file tokens are rejected. No query parameters. This workflow reserves one inspection unit and writes inspection
        admission/observation metadata while leaving file/object lifecycle and provider data unchanged. Inspection allowance uses SQL UTC days. Owner: 200 requests/2000 units
        across projects, platform owner lane 2000/20000. Operator principal: 500/5000, platform operator lane 1000/10000. One active handler per principal, three per lane; lease 30 seconds
        and wrapper deadline 20 seconds. Reservations never refund. Statements are submission observations, not verified executions. D1 row counts are reported only when exposed by trusted
        response metadata; missing counts are unknown. Metering/authentication baseline, finalization and late work are excluded; all observations remain incomplete and unverified
        as actual charges. The current request reservation can appear in the same-day report before its own query observations are finalized.'
      responses:
        '200':
          description: Private aggregate inspection usage; currentInspectionFinalized false
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Reserved fixed work weight for an admitted workflow; not a price or billed-row count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageControlOwnerUsage'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Current owner session required; file bearers rejected
        '404':
          description: Project/current owner authorization unavailable
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: 'Inspection request/unit/slot capacity exhausted. Retry-After value 30 is only a retry hint; daily exhaustion can last until the SQL UTC date resets.'
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Seconds before a suggested retry, not an availability guarantee.
        '503':
          description: Inspection admission or aggregate metadata unavailable
        '504':
          description: Inspection workflow exceeded its 20-second deadline
        '403':
          description: Invalid browser request origin
        '405':
          description: Only GET supported
  /api/operator/object-storage/usage:
    get:
      operationId: getOperatorStorageControlUsage
      security:
      - ObjectStorageOperatorToken: []
      description: 'Requires the separate operator bearer on the exact canonical HTTPS origin, without Cookie or Origin headers. No query parameters. This workflow reserves one
        inspection unit and writes inspection admission/observation metadata while leaving file/object lifecycle and provider data unchanged. Inspection allowance uses SQL UTC
        days. Owner: 200 requests/2000 units across projects, platform owner lane 2000/20000. Operator principal: 500/5000, platform operator lane 1000/10000. One active handler
        per principal, three per lane; lease 30 seconds and wrapper deadline 20 seconds. Reservations never refund. Statements are submission observations, not verified executions. D1 row counts
        are reported only when exposed by trusted response metadata; missing counts are unknown. Metering/authentication baseline, finalization and late work are excluded; all
        observations remain incomplete and unverified as actual charges. The current request reservation can appear in the same-day report before its own query observations are
        finalized.'
      responses:
        '200':
          description: Private aggregate inspection usage; currentInspectionFinalized false
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Reserved fixed work weight for an admitted workflow; not a price or billed-row count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageControlOperatorUsage'
        '400':
          description: Query parameters are unsupported
        '401':
          description: Separate operator bearer required; Cookie and Origin headers rejected
        '404':
          description: Canonical route or operator credential unavailable
        '409':
          description: Inspection lease or authorization changed; refresh
        '429':
          description: 'Inspection request/unit/slot capacity exhausted. Retry-After value 30 is only a retry hint; daily exhaustion can last until the SQL UTC date resets.'
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Seconds before a suggested retry, not an availability guarantee.
        '503':
          description: Inspection admission or aggregate metadata unavailable
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/projects/{projectId}/files/activity:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectObjectActivity
      security:
      - OwnerSession: []
      description: Read a private metadata-only lifecycle summary for the current project owner. The captured owner, identity and account eligibility are rechecked in the SQL
        snapshot. File bearer tokens cannot use this endpoint. No object provider is queried, no file/object key or body is returned, and file/object lifecycle remains unchanged;
        inspection admission and observation metadata is written. D1 remains primary; hosted/provider acceptance is pending. Inspection admission reserves 1 fixed work units
        with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds.
      responses:
        '200':
          description: Owner object activity metadata; private, no-store; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProjectObjectOverview'
                - type: object
                  required:
                  - projectId
                  properties:
                    scope:
                      const: project
                    projectId:
                      type: string
                      format: uuid
        '401':
          description: Owner session required; file bearer tokens are unsupported
        '403':
          description: Invalid browser request origin
        '404':
          description: Project inaccessible or current authorization no longer valid
        '405':
          description: Only GET is supported
        '409':
          description: Inspection lease, authorization or review evidence changed; refresh
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
        '503':
          description: Inspection admission or metadata unavailable
  /api/operator/object-storage:
    get:
      operationId: getOperatorObjectStorageMetadata
      security:
      - ObjectStorageOperatorToken: []
      description: Read redacted platform object lifecycle metadata on the exact canonical HTTPS origin. Requires a separately configured operator bearer token and rejects Cookie
        and Origin headers. This route leaves file/object lifecycle and provider data unchanged; admission and observation metadata is written. D1 remains primary. State and
        cursor filter only the queue page; summary counts cover the complete platform scope. Inspection admission reserves 1 fixed work units with no refund; units are not D1
        rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds.
      parameters:
      - in: query
        name: state
        description: Optional lifecycle state. Without a state filter, cleaned entries are excluded from the queue.
        schema:
          enum:
          - pending
          - writing
          - verified
          - cleanup
          - held
          - cleaned
      - in: query
        name: cursor
        description: Opaque nextCursor from the previous page. Preserve the selected state when paging. Duplicate and unknown query parameters are rejected.
        schema:
          type: string
          maxLength: 54
          pattern: ^(0|[1-9][0-9]{0,15})_[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
      responses:
        '200':
          description: Private lifecycle metadata and up to 25 queue entries, ordered newest first; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ProjectObjectOverview'
                - type: object
                  required:
                  - queue
                  - queueState
                  - nextCursor
                  properties:
                    scope:
                      const: platform
                    queueState:
                      type:
                      - string
                      - 'null'
                      enum:
                      - pending
                      - writing
                      - verified
                      - cleanup
                      - held
                      - cleaned
                      - null
                    nextCursor:
                      type:
                      - string
                      - 'null'
                      maxLength: 54
                    queue:
                      type: array
                      maxItems: 25
                      items:
                        $ref: '#/components/schemas/ObjectLifecycleQueueEntry'
        '400':
          description: Invalid
          repeated or unsupported queue filter: null
        '401':
          description: Operator bearer credential required; cookies and Origin headers are rejected
        '404':
          description: Canonical route unavailable or operator credential not configured
        '503':
          description: Metadata database or schema unavailable
        '409':
          description: Inspection lease, authorization or review evidence changed; refresh
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/operator/object-storage/{attemptId}/review:
    parameters:
    - $ref: '#/components/parameters/ObjectAttemptId'
    get:
      operationId: getOperatorObjectReconciliationReview
      security:
      - ObjectStorageOperatorToken: []
      description: Inspect one attempt with a metadata-only SQL snapshot and return an advisory assessment and unsigned proposal. Requires the exact canonical HTTPS origin and
        the separate operator bearer credential, without Cookie, Origin or query parameters. No provider is queried and no resource claim, hold, retry allowance, publication
        or billing state changes; inspection admission/observation metadata is written. D1 remains primary; hosted/provider acceptance is pending. Inspection admission reserves
        16 fixed work units with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline
        is 20 seconds.
      responses:
        '200':
          description: Private metadata snapshot and advisory review; no execution or approval authority; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectReconciliationReview'
        '400':
          description: Invalid request or unsupported query parameters
        '401':
          description: Operator bearer credential required; cookies and Origin headers are rejected
        '404':
          description: Canonical route unavailable, credential not configured or attempt inaccessible
        '503':
          description: Metadata database/schema unavailable or bounded evidence cannot be represented safely
        '409':
          description: Inspection lease, authorization or review evidence changed; refresh
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/operator/object-storage/{attemptId}/review-check:
    parameters:
    - $ref: '#/components/parameters/ObjectAttemptId'
    post:
      operationId: checkOperatorObjectReconciliationReview
      security:
      - ObjectStorageOperatorToken: []
      description: Check the raw unsigned proposal against fresh SQL metadata, without applying it or changing file/object lifecycle; inspection admission/observation metadata
        is written. Same dedicated operator credential and canonical HTTPS restrictions as inspection; no Cookie, Origin or query parameters. Request JSON is limited to 16 KiB,
        depth 10, 2000 structural tokens and a two-second read deadline. Stale, expired, cross-target, content or available-action changes reject the review. A public SHA digest
        is content binding, not issuer authentication or owner/operator confirmation. Every execution and approval flag stays false. Inspection admission reserves 16 fixed work
        units with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReconciliationProposal'
      responses:
        '200':
          description: Matching current-equivalence review only; valid true grants no approval
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectReconciliationValidation'
        '409':
          description: Rejected proposal with reason codes; no action performed
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectReconciliationValidation'
        '400':
          description: Invalid request or unsupported query parameters
        '401':
          description: Operator bearer credential required; cookies and Origin headers are rejected
        '404':
          description: Canonical route unavailable, credential not configured or attempt inaccessible
        '503':
          description: Metadata database/schema unavailable or bounded evidence cannot be represented safely
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 16 KiB
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/operator/object-storage/{attemptId}/reviews:
    parameters:
    - $ref: '#/components/parameters/ObjectAttemptId'
    post:
      operationId: issueOperatorObjectReviewRecord
      security:
      - ObjectStorageOperatorToken: []
      description: Uses the separate object-storage operator bearer credential on the exact canonical HTTPS origin; Cookie and Origin headers are rejected. Create a server record
        from fresh current metadata, or return the same operator-principal/requestId record when its attempt and requested action match. The client cannot provide the packet
        or expiry. Original five-minute expiry never extends. Issuance is limited to 50 admissions per owner and 500 platform-wide per SQL UTC day; active caps are three per
        attempt, 20 per project and 100 platform-wide. Writes affect review receipts and inspection admission/observation metadata only. Object lifecycle, holds, provider transport,
        retry allowances, publication and billing remain unchanged; all seven authority flags remain false. Send strict application/json, at most 4 KiB, depth six, 200 structural
        tokens and a two-second body-read deadline. Unknown fields and query parameters are rejected.  Inspection admission reserves 16 fixed work units with no refund; units
        are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOperatorReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Operator credential required; browser credentials are rejected
        '404':
          description: Canonical route or credential unavailable, review/attempt inaccessible or issuance owner unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 4 KiB
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReviewIssueRequest'
  /api/operator/object-storage/reviews:
    get:
      operationId: listOperatorObjectReviewRecords
      security:
      - ObjectStorageOperatorToken: []
      description: Uses the separate object-storage operator bearer credential on the exact canonical HTTPS origin; Cookie and Origin headers are rejected. List up to 25 newest
        records. Summary current/effective fields are false; open detail to check evidence. Writes affect review receipts and inspection admission/observation metadata only.
        Object lifecycle, holds, provider transport, retry allowances, publication and billing remain unchanged; all seven authority flags remain false. Inspection admission
        reserves 2 fixed work units with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper
        deadline is 20 seconds.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOperatorReviewList'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Operator credential required; browser credentials are rejected
        '404':
          description: Canonical route or credential unavailable, review/attempt inaccessible or issuance owner unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
      parameters:
      - in: query
        name: cursor
        description: Opaque nextCursor from the previous page. Duplicate and unknown query parameters are rejected.
        schema:
          type: string
          maxLength: 54
          pattern: ^(0|[1-9][0-9]{0,15})_[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
  /api/operator/object-storage/reviews/{recordId}:
    parameters:
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    get:
      operationId: getOperatorObjectReviewRecord
      security:
      - ObjectStorageOperatorToken: []
      description: Uses the separate object-storage operator bearer credential on the exact canonical HTTPS origin; Cookie and Origin headers are rejected. Inspect a stored packet
        with fresh SQL evidence and current authorization. Operator token rotation makes prior confirmations ineffective and requires a new record for further confirmation. These
        requests change review receipts only. Object lifecycle, holds, provider transport, retry allowances, publication and billing remain unchanged; all seven authority flags
        remain false. Inspection admission reserves 16 fixed work units with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second
        lease expires; the wrapper deadline is 20 seconds. Expired or withdrawn historical detail skips private-evidence reconstruction while retaining the fixed detail weight.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOperatorReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Operator credential required; browser credentials are rejected
        '404':
          description: Canonical route or credential unavailable, review/attempt inaccessible or issuance owner unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/operator/object-storage/reviews/{recordId}/confirmation:
    parameters:
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    post:
      operationId: confirmOperatorObjectReviewRecord
      security:
      - ObjectStorageOperatorToken: []
      description: Uses the separate object-storage operator bearer credential on the exact canonical HTTPS origin; Cookie and Origin headers are rejected. Record or revoke this
        operator channel acknowledgement using exact expected revision and proposal digest. New confirmation requires unchanged current evidence, owner authority, unexpired packet
        and issuing operator principal. Revocation remains available after expiry, stale evidence or credential rotation. Eight confirmation transitions are permitted; revocation
        remains possible. Writes affect review receipts and inspection admission/observation metadata only. Object lifecycle, holds, provider transport, retry allowances, publication
        and billing remain unchanged; all seven authority flags remain false. Send strict application/json, at most 4 KiB, depth six, 200 structural tokens and a two-second body-read
        deadline. Unknown fields and query parameters are rejected.  Inspection admission reserves 16 fixed work units with no refund; units are not D1 rows or dollars. Unknown
        outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds. Only confirmed:true uses inspection admission. Authenticated confirmed:false
        bypasses this allowance and returns a cheap unchecked receipt with current/effective false; open detail for current evidence.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOperatorReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Operator credential required; browser credentials are rejected
        '404':
          description: Canonical route or credential unavailable, review/attempt inaccessible or issuance owner unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 4 KiB
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReviewConfirmationRequest'
  /api/operator/object-storage/reviews/{recordId}/withdraw:
    parameters:
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    post:
      operationId: withdrawOperatorObjectReviewRecord
      security:
      - ObjectStorageOperatorToken: []
      description: Uses the separate object-storage operator bearer credential on the exact canonical HTTPS origin; Cookie and Origin headers are rejected. Withdraw the record
        using its current revision and digest. Historical authenticated withdrawal remains available after expiry, stale evidence or operator rotation. These requests change
        review receipts only. Object lifecycle, holds, provider transport, retry allowances, publication and billing remain unchanged; all seven authority flags remain false.
        Send strict application/json, at most 4 KiB, depth six, 200 structural tokens and a two-second body-read deadline. Unknown fields and query parameters are rejected.  Withdrawal
        bypasses inspection quota and returns a cheap unchecked receipt with current/effective false until a separate detail read. Authentication and CAS checks still apply.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority
          headers:
            Cache-Control:
              schema:
                const: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOperatorReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Operator credential required; browser credentials are rejected
        '404':
          description: Canonical route or credential unavailable, review/attempt inaccessible or issuance owner unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 4 KiB
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReviewWithdrawalRequest'
  /api/projects/{projectId}/file-reviews:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listOwnerObjectReviewRecords
      security:
      - OwnerSession: []
      description: Requires the current project owner workspace session; file tokens and operator bearers cannot establish this owner channel. List up to 25 newest records for
        this owner. Includes the file key and expected size to identify the staged copy. Summary current/effective fields are false; open detail to check evidence. These requests
        change review receipts only. Object lifecycle, holds, provider transport, retry allowances, publication and billing remain unchanged; all seven authority flags remain
        false. Inspection admission reserves 2 fixed work units with no refund; units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second
        lease expires; the wrapper deadline is 20 seconds.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOwnerReviewList'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Current owner session required; bearer substitution is rejected
        '404':
          description: Review/project inaccessible or current owner authorization unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '403':
          description: Invalid browser request origin
        '405':
          description: Unsupported method
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
      parameters:
      - in: query
        name: cursor
        description: Opaque nextCursor from the previous page. Duplicate and unknown query parameters are rejected.
        schema:
          type: string
          maxLength: 54
          pattern: ^(0|[1-9][0-9]{0,15})_[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
  /api/projects/{projectId}/file-reviews/{recordId}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    get:
      operationId: getOwnerObjectReviewRecord
      security:
      - OwnerSession: []
      description: Requires the current project owner workspace session; file tokens and operator bearers cannot establish this owner channel. Inspect fresh current evidence
        before an explicit owner acknowledgement. Owner views include fileKey and expectedBytes. Historical reads remain available with current owner authorization when operator
        configuration is removed. Writes affect review receipts and inspection admission/observation metadata only. Object lifecycle, holds, provider transport, retry allowances,
        publication and billing remain unchanged; all seven authority flags remain false. Inspection admission reserves 16 fixed work units with no refund; units are not D1 rows
        or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds. Expired or withdrawn historical detail skips
        private-evidence reconstruction while retaining the fixed detail weight.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority; inspection metadata is written, resource state unchanged
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOwnerReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Current owner session required; bearer substitution is rejected
        '404':
          description: Review/project inaccessible or current owner authorization unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '403':
          description: Invalid browser request origin
        '405':
          description: Unsupported method
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
  /api/projects/{projectId}/file-reviews/{recordId}/confirmation:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    post:
      operationId: confirmOwnerObjectReviewRecord
      security:
      - OwnerSession: []
      description: Requires the current project owner workspace session; file tokens and operator bearers cannot establish this owner channel. Record or revoke this owner channel
        acknowledgement with exact expected revision and proposal digest. New confirmation needs current unchanged evidence, unexpired packet and the issuing operator principal
        still configured. Revocation remains available after evidence changes, expiry or operator removal. The console requires an explicit unchecked acknowledgement before recording.
        Writes affect review receipts and inspection admission/observation metadata only. Object lifecycle, holds, provider transport, retry allowances, publication and billing
        remain unchanged; all seven authority flags remain false. Owner writes require a same-origin Origin header. Send strict application/json, at most 4 KiB, depth six, 200
        structural tokens and a two-second body-read deadline. Unknown fields and query parameters are rejected.  Inspection admission reserves 16 fixed work units with no refund;
        units are not D1 rows or dollars. Unknown outcomes retain their handler slot until its 30-second lease expires; the wrapper deadline is 20 seconds. Only confirmed:true
        uses inspection admission. Authenticated confirmed:false bypasses this allowance and returns a cheap unchecked receipt with current/effective false; open detail for current
        evidence.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority
          headers:
            Cache-Control:
              schema:
                const: private, no-store
            X-Stackr-Inspection-Units:
              schema:
                type: integer
                enum:
                - 1
                - 2
                - 16
              description: Fixed work units reserved for an admitted inspection; absent for bypassed negative acknowledgements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOwnerReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Current owner session required; bearer substitution is rejected
        '404':
          description: Review/project inaccessible or current owner authorization unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '403':
          description: Invalid browser request origin
        '405':
          description: Unsupported method
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 4 KiB
        '415':
          description: Send application/json
        '429':
          description: Inspection request/unit/slot capacity or record issuance capacity exhausted. Inspection admission denial includes Retry-After value 30 as a hint; daily exhaustion
            can persist until the SQL UTC date resets.
          headers:
            Retry-After:
              schema:
                const: '30'
              description: Suggested seconds before retry; absent for other record-capacity responses and never a guarantee.
        '504':
          description: Inspection workflow exceeded its 20-second deadline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReviewConfirmationRequest'
  /api/projects/{projectId}/file-reviews/{recordId}/withdraw:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    - $ref: '#/components/parameters/ObjectReviewRecordId'
    post:
      operationId: withdrawOwnerObjectReviewRecord
      security:
      - OwnerSession: []
      description: Requires the current project owner workspace session; file tokens and operator bearers cannot establish this owner channel. Withdraw this owner review record
        with its current revision and digest. Historical authenticated withdrawal remains available after evidence changes, expiry or operator removal. These requests change
        review receipts only. Object lifecycle, holds, provider transport, retry allowances, publication and billing remain unchanged; all seven authority flags remain false.
        Owner writes require a same-origin Origin header. Send strict application/json, at most 4 KiB, depth six, 200 structural tokens and a two-second body-read deadline. Unknown
        fields and query parameters are rejected.  Withdrawal bypasses inspection quota and returns a cheap unchecked receipt with current/effective false until a separate detail
        read. Authentication and CAS checks still apply.
      responses:
        '200':
          description: Private server review receipt; no execution or approval authority
          headers:
            Cache-Control:
              schema:
                const: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectOwnerReviewRecord'
        '400':
          description: Invalid request, proof, cursor or unsupported fields/query parameters
        '401':
          description: Current owner session required; bearer substitution is rejected
        '404':
          description: Review/project inaccessible or current owner authorization unavailable
        '409':
          description: Stale evidence, expiry, changed operator, revision/digest conflict or confirmation limit; refresh or obtain a new record
        '503':
          description: Review database/schema or complete bounded evidence unavailable
        '403':
          description: Invalid browser request origin
        '405':
          description: Unsupported method
        '408':
          description: Request body aborted or read deadline exceeded
        '413':
          description: Request body exceeds 4 KiB
        '415':
          description: Send application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectReviewWithdrawalRequest'
  /api/projects/{projectId}/release-routing:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectReleaseRouting
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Current canary with opaque revision, optional deadline, and named preview channels
          content:
            application/json:
              schema:
                type: object
                required: [canary, channels, channelLimit, healthGuardAvailable]
                properties:
                  canary: { $ref: '#/components/schemas/ProjectCanary' }
                  channels:
                    type: array
                    items:
                      type: object
                      required: [name, deploymentId, updatedAt]
                      properties:
                        name: { type: string }
                        deploymentId: { type: string, format: uuid }
                        updatedAt: { type: integer, format: int64, description: Unix milliseconds }
                  channelLimit: { type: integer }
                  healthGuardAvailable: { type: boolean, description: Whether Stackr can evaluate rollout health from sampled requests. }
        '404': { description: Project not found }
  /api/projects/{projectId}/release-routing/canary:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    put:
      operationId: setProjectCanary
      security: [{ OwnerSession: [] }]
      description: Omitting both deadline fields preserves the active deadline. A deadline-only edit changes the revision while preserving the metrics window.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [candidateDeploymentId, trafficBasisPoints]
              not:
                required: [expiresAt, durationMinutes]
              properties:
                candidateDeploymentId: { type: string, format: uuid }
                baselineDeploymentId: { type: string, format: uuid }
                trafficBasisPoints: { type: integer, minimum: 1, maximum: 10000 }
                stageBasisPoints:
                  $ref: '#/components/schemas/ProjectRolloutStages'
                  description: Set only when starting a new split. Send expectedRevision as null and trafficBasisPoints as the first stage.
                expectedRevision:
                  type: [string, 'null']
                  pattern: '^[a-f0-9]{32}$'
                  description: Supply the current canary revision. Use null to require no active split.
                expiresAt:
                  type: [integer, 'null']
                  format: int64
                  description: Future deadline in Unix milliseconds, up to 24 hours ahead. Use null to clear the deadline.
                durationMinutes:
                  type: integer
                  minimum: 1
                  maximum: 1440
                  description: Minutes until traffic returns to the live release, measured from the server clock.
                healthGuard:
                  description: Omit to preserve the rule. Send null to clear it. When provided, expectedRevision is required.
                  anyOf:
                    - $ref: '#/components/schemas/RolloutHealthGuard'
                    - type: 'null'
      responses:
        '200':
          description: Saved canary with revision, metrics start timestamp, and optional deadline
          content:
            application/json:
              schema:
                type: object
                required: [canary]
                properties:
                  canary: { $ref: '#/components/schemas/ProjectCanary' }
        '400': { description: Invalid release, traffic percentage, revision, or deadline }
        '409': { description: Stale split, incompatible release, or release policy conflict }
        '503': { description: Request sampling is unavailable for rollout health rules }
    delete:
      operationId: stopProjectCanary
      security: [{ OwnerSession: [] }]
      parameters:
        - in: query
          name: expectedRevision
          description: Current canary revision from the last routing read.
          schema: { type: string, pattern: '^[a-f0-9]{32}$' }
      responses:
        '200': { description: Traffic restored to the live release }
        '409': { description: Rollout changed since the supplied revision }
  /api/projects/{projectId}/release-routing/advance:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: advanceProjectRollout
      security: [{ OwnerSession: [] }]
      description: Advance a staged rollout one step and start a fresh comparison window. Use the final step revision to publish through activate-release.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [expectedRevision]
              properties:
                expectedRevision: { type: string, pattern: '^[a-f0-9]{32}$' }
      responses:
        '200':
          description: Updated rollout
          content:
            application/json:
              schema:
                type: object
                required: [canary]
                properties:
                  canary: { $ref: '#/components/schemas/ProjectCanary' }
        '400': { description: Invalid revision }
        '404': { description: Project not found }
        '409': { description: Stale or expired split, final stage reached, or release policy conflict }
  /api/projects/{projectId}/release-routing/history:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listProjectRolloutHistory
      security: [{ OwnerSession: [] }]
      description: Returns up to 50 changes, newest first. Stackr records expired splits during cleanup or when a new split replaces them.
      responses:
        '200':
          description: Traffic split history
          content:
            application/json:
              schema:
                type: object
                required: [events, limit]
                properties:
                  events:
                    type: array
                    maxItems: 50
                    items: { $ref: '#/components/schemas/ProjectRolloutEvent' }
                  limit: { type: integer, const: 50 }
        '404': { description: Project not found }
  /api/projects/{projectId}/release-routing/metrics:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectRolloutMetrics
      security: [{ OwnerSession: [] }]
      parameters:
        - in: query
          name: minutes
          schema: { type: integer, enum: [15, 60, 360, 1440], default: 60 }
      responses:
        '200':
          description: Current split and baseline and candidate measurements for sampled GET and HEAD requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled: { type: boolean }
                  window:
                    type: object
                    properties:
                      minutes: { type: integer }
                      from: { type: string, format: date-time }
                      to: { type: string, format: date-time }
                  rollout:
                    type: [object, 'null']
                    properties:
                      baselineDeploymentId: { type: string, format: uuid }
                      candidateDeploymentId: { type: string, format: uuid }
                      trafficBasisPoints: { type: integer }
                      updatedAt: { type: integer, description: Last split change in epoch milliseconds }
                      stages: { $ref: '#/components/schemas/ProjectRolloutStages' }
                      stageIndex: { type: integer, minimum: 0, maximum: 4, description: Zero-based stage index for staged rollouts }
                  baseline: { $ref: '#/components/schemas/RolloutSampleMetrics' }
                  candidate: { $ref: '#/components/schemas/RolloutSampleMetrics' }
                  observedCandidateBasisPoints: { type: [integer, 'null'], minimum: 0, maximum: 10000 }
        '400': { description: Unsupported metrics window }
        '404': { description: Project not found }
  /api/projects/{projectId}/release-webhooks:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listProjectReleaseWebhooks
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Availability, limits and subscriptions with delivery totals }
        '404': { description: Project not found }
    post:
      operationId: createProjectReleaseWebhook
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [target, events]
              additionalProperties: false
              properties:
                target: { type: string, format: uri, description: Supported HTTPS destination }
                events:
                  type: array
                  minItems: 1
                  uniqueItems: true
                  items: { type: string, enum: [release-staged, release-published, project-paused, release-failed, release-removed] }
      responses:
        '201': { description: Inactive subscription and its one-time signing secret }
        '400': { description: Invalid destination or event selection }
        '403': { description: Same-origin owner write required }
        '409': { description: Duplicate destination or subscription cap reached }
  /api/projects/{projectId}/release-webhooks/{webhookId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ReleaseWebhookId'
    patch:
      operationId: setProjectReleaseWebhookEnabled
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              additionalProperties: false
              properties:
                enabled: { type: boolean }
      responses:
        '200': { description: Updated webhook }
        '409': { description: Verification required before enabling }
    delete:
      operationId: deleteProjectReleaseWebhook
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Webhook revoked }
        '404': { description: Webhook not found }
  /api/projects/{projectId}/release-webhooks/{webhookId}/challenge:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ReleaseWebhookId'
    post:
      operationId: createProjectReleaseWebhookChallenge
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Verification value and expiry in epoch milliseconds }
        '409': { description: Destination already verified or webhook unavailable }
  /api/projects/{projectId}/release-webhooks/{webhookId}/verify:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ReleaseWebhookId'
    post:
      operationId: verifyProjectReleaseWebhook
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Verified and enabled webhook }
        '409': { description: Challenge unavailable or expired }
        '422': { description: Endpoint did not return the expected value }
        '429': { description: Verification limit reached }
  /api/projects/{projectId}/release-webhooks/{webhookId}/rotate:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ReleaseWebhookId'
    post:
      operationId: rotateProjectReleaseWebhookSecret
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Paused webhook and its one-time replacement signing secret }
        '403': { description: Same-origin owner write required }
        '404': { description: Webhook not found }
        '409': { description: Endpoint verification required or signing version changed }
  /api/projects/{projectId}/release-webhooks/{webhookId}/deliveries:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ReleaseWebhookId'
    get:
      operationId: listProjectReleaseWebhookDeliveries
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Up to 30 recent webhook delivery outcomes }
        '404': { description: Webhook not found }
  /api/projects/{projectId}/web-analytics:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectWebAnalytics
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Recording settings, UTC day totals, top configured pages, and referrer source totals }
        '401': { description: Stackr sign-in required }
        '404': { description: Project not found }
    put:
      operationId: saveProjectWebAnalytics
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [revision, enabled, paths]
              additionalProperties: false
              properties:
                revision: { type: integer, minimum: 0 }
                enabled: { type: boolean }
                paths:
                  type: array
                  maxItems: 12
                  items: { type: string, description: Exact public app-relative path without query strings }
      responses:
        '200': { description: Saved settings and current aggregates }
        '400': { description: Invalid recording settings or page paths }
        '403': { description: Same-origin owner write required }
        '404': { description: Project not found }
        '409': { description: Settings changed since the supplied revision }
  /api/projects/{projectId}/rewrites:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectRewrites
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Current revision, exact rewrite rules, and rule limit }
        '404': { description: Project not found }
    put:
      operationId: saveProjectRewrites
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [revision, rewrites]
              properties:
                revision: { type: integer, minimum: 0 }
                rewrites:
                  type: array
                  maxItems: 32
                  items:
                    type: object
                    required: [from, to]
                    additionalProperties: false
                    properties:
                      from: { type: string, maxLength: 200, description: Exact app-relative path or folder pattern ending in /* }
                      to: { type: string, maxLength: 200, description: Exact static file path or destination folder pattern ending in /* }
      responses:
        '200': { description: Saved rules and new revision }
        '400': { description: Invalid rule, reserved path, or rewrite chain }
        '403': { description: Same-origin owner write required }
        '404': { description: Project not found }
        '409': { description: Rules changed since the supplied revision }
  /api/projects/{projectId}/release-events:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readProjectReleaseEvents
      security: [{ OwnerSession: [] }, { ProjectReleaseEventFeedToken: [] }]
      parameters:
        - in: query
          name: after
          schema: { type: string }
          description: The previous nextCursor or the resetCursor supplied for an expired cursor.
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100 }
      responses:
        '200': { description: Ordered release events, nextCursor, hasMore, and retention information }
        '401': { description: Sign-in or valid project feed token required }
        '404': { description: Project not found }
        '410': { description: The cursor fell behind retained history. Response includes resetCursor. }
  /api/projects/{projectId}/release-events/token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readProjectReleaseEventFeedTokenStatus
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Active token expiry, without the credential }
    post:
      operationId: issueProjectReleaseEventFeedToken
      security: [{ OwnerSession: [] }]
      responses:
        '201': { description: New read-only bearer token disclosed once. Any prior token is revoked. }
    delete:
      operationId: revokeProjectReleaseEventFeedToken
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Project feed token revoked }
  /api/projects/{projectId}/leads/read-token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getInquiryReadTokenStatus
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Expiration and today's read usage
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InquiryReadTokenStatus' }
        '404': { description: Project unavailable }
    post:
      operationId: rotateInquiryReadToken
      description: Issue a new 30-day credential and invalidate the previous one. Save the token from this response.
      security: [{ OwnerSession: [] }]
      responses:
        '201':
          description: Token issued
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/InquiryReadTokenStatus'
                  - type: object
                    required: [token]
                    properties:
                      token: { type: string, pattern: '^sir_[A-Za-z0-9_-]{43}$' }
        '404': { description: Project unavailable }
        '409': { description: Inquiry queue notifications are disabled }
    delete:
      operationId: revokeInquiryReadToken
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Credential revoked
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InquiryReadTokenStatus' }
        '404': { description: Project unavailable }
  /api/inquiry-records/{projectId}/{inquiryId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - { name: inquiryId, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      operationId: getNotifiedInquiry
      description: Read a single inquiry with a retained notification job. Call from a server using the bearer token.
      security: [{ InquiryReadToken: [] }]
      responses:
        '200':
          description: Inquiry
          content:
            application/json:
              schema:
                type: object
                required: [inquiry]
                properties:
                  inquiry:
                    type: object
                    required: [id, name, email, message, createdAt]
                    properties:
                      id: { type: string, format: uuid }
                      name: { type: string }
                      email: { type: string, format: email }
                      message: { type: string }
                      createdAt: { type: string, format: date-time }
        '401': { description: Invalid or inactive credential }
        '404': { description: Inquiry unavailable }
        '429': { description: Daily read allowance reached }
  /api/status-incidents:
    get:
      operationId: listWorkspaceStatusIncidents
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Workspace incidents, limits and public link state }
        '401': { description: Owner session required }
    post:
      operationId: openWorkspaceStatusIncident
      description: Publish an investigating incident to the enabled shared status page.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [title, severity, message]
              properties:
                title: { type: string, minLength: 1, maxLength: 100 }
                severity: { type: string, enum: [minor, major, critical] }
                message: { type: string, minLength: 1, maxLength: 600 }
      responses:
        '201': { description: Incident opened }
        '409': { description: Status link unavailable or incident capacity reached }
        '429': { description: Daily incident allowance reached }
  /api/status-incidents/{incidentId}:
    parameters:
      - { name: incidentId, in: path, required: true, schema: { type: string, format: uuid } }
    patch:
      operationId: updateWorkspaceStatusIncident
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [status, message, revision]
              properties:
                status: { type: string, enum: [investigating, identified, monitoring, resolved] }
                message: { type: string, minLength: 1, maxLength: 600 }
                revision: { type: integer, minimum: 0 }
      responses:
        '200': { description: Incident updated }
        '404': { description: Incident unavailable }
        '409': { description: Stale revision, update unavailable or update limit reached }
    delete:
      operationId: retractWorkspaceStatusIncident
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Incident retracted }
        '404': { description: Incident unavailable }
  /api/public/status/{statusKey}:
    parameters:
      - { name: statusKey, in: path, required: true, schema: { type: string, pattern: '^[a-f0-9]{64}$' } }
    get:
      operationId: getSharedWorkspaceStatus
      security: []
      responses:
        '200': { description: Public apps, usage, charges and the 12 most recent incidents with open incidents first }
        '404': { description: Status page unavailable }
  /api/queue-webhooks/{endpointId}:
    parameters:
      - $ref: '#/components/parameters/QueueWebhookId'
    post:
      operationId: receiveQueueWebhook
      description: Verify a Standard Webhooks v1 HMAC signature over the raw JSON and enqueue the original payload.
      security: []
      parameters:
        - in: header
          name: webhook-id
          required: true
          schema: { type: string, maxLength: 128, pattern: '^[A-Za-z0-9_:-]+$' }
        - in: header
          name: webhook-timestamp
          required: true
          schema: { type: string, pattern: '^[1-9][0-9]{0,11}$' }
          description: Unix seconds within five minutes of delivery.
        - in: header
          name: webhook-signature
          required: true
          schema: { type: string, maxLength: 512 }
          description: Standard Webhooks v1 HMAC-SHA256 signatures.
      requestBody:
        required: true
        content:
          application/json:
            schema: { description: JSON payload up to 8 KiB }
      responses:
        '200': { description: Existing job for this delivery }
        '201': { description: Job accepted }
        '401': { description: Invalid signature or inactive endpoint }
        '409': { description: Delivery conflicts with existing job or queue capacity reached }
        '413': { description: Payload too large }
        '429': { description: Queue operation allowance reached }
  /api/projects/{projectId}/queues/webhooks:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listProjectQueueWebhooks
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Endpoint metadata, availability and limits }
    post:
      operationId: createProjectQueueWebhook
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, queue]
              properties:
                name: { type: string, minLength: 1, maxLength: 48 }
                queue: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
      responses:
        '201': { description: Endpoint metadata and one-time signing secret }
        '409': { description: Endpoint name or capacity conflict }
  /api/projects/{projectId}/queues/webhooks/{endpointId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/QueueWebhookId'
    post:
      operationId: rotateProjectQueueWebhookSecret
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Endpoint metadata and new one-time signing secret }
        '404': { description: Endpoint unavailable }
    delete:
      operationId: deleteProjectQueueWebhook
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Endpoint deleted }
        '404': { description: Endpoint unavailable }
  /api/projects/{projectId}/leads:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listProjectInquiries
      security: [{ OwnerSession: [] }]
      parameters:
        - in: query
          name: state
          schema: { type: string, enum: [new, contacted, closed] }
      responses:
        '200': { description: Owner inbox entries, totals by status and capacity }
        '404': { description: Project unavailable }
  /api/projects/{projectId}/leads/{leadId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: leadId
        required: true
        schema: { type: string, format: uuid }
    patch:
      operationId: updateProjectInquiryStatus
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [state, revision]
              properties:
                state: { type: string, enum: [new, contacted, closed] }
                revision: { type: integer, minimum: 0 }
      responses:
        '200': { description: Current inquiry status and revision }
        '404': { description: Inquiry unavailable }
        '409': { description: Inquiry changed since it was read }
  /api/projects/{projectId}/leads/queue:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getInquiryQueueRule
      description: Read the destination and delivery counters for new inquiry notifications.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Queue name, pending and dropped counts, and last delivery timestamp }
    put:
      operationId: setInquiryQueueRule
      description: Send new inquiry IDs to a named queue without copying contact details.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [queue]
              properties:
                queue: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
      responses:
        '200': { description: Updated queue destination and delivery counters }
    delete:
      operationId: disableInquiryQueueRule
      description: Stop sending new inquiry notifications and discard pending deliveries.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Disabled queue rule and delivery counters }
  /api/projects/{projectId}/database:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerRecordsDatabase
      description: Read the current owner's Records database metadata and limits, or database null when no store exists. Current session/account/pilot/identity/access epoch and store lifecycle are checked before return. No private authorization epoch or generation is exposed.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Records metadata and fixed limits
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectRecordsState' }
        '401': { description: Current owner session required }
        '404': { description: Project or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Captured Records store changed; refresh }
        '503': { description: Records metadata, current policy or valid current-period usage could not be verified }
    post:
      operationId: createOwnerRecordsDatabase
      description: Create one JSON Records store for the current owner. JSON is limited to 512 bytes, depth 4 and 512 structural tokens, with a five-second body-read deadline. Captured session/owner/account policy and store lifecycle are rechecked atomically before creation and before return.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, minLength: 2, maxLength: 64 }
      responses:
        '201':
          description: Records store created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectRecordsCreated' }
        '400': { description: Invalid name, JSON, UTF-8, declared body length or structure }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project or current owner authorization unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Store already exists or captured store lifecycle changed }
        '413': { description: JSON body exceeds 512 bytes }
        '503': { description: Current Records authorization, policy or database state could not be verified }
    delete:
      operationId: deleteOwnerRecordsDatabase
      description: Delete the Records store and its records after confirming its exact name. The captured original store lifecycle and current owner/session/account policy must still match. JSON is bounded to 512 bytes, depth 4 and 512 structural tokens with a five-second read deadline. This does not refund monthly operation reservations or delete retained schedule backups.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, description: Exact current Records database name }
      responses:
        '200':
          description: Confirmed Records store deleted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [deleted]
                properties:
                  deleted: { const: true }
        '400': { description: Invalid confirmation body, JSON, UTF-8, length or structure }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project, store or current owner authorization unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Name confirmation did not match or captured store lifecycle changed }
        '413': { description: JSON body exceeds 512 bytes }
        '503': { description: Current Records authorization, policy or database state could not be verified }
  /api/projects/{projectId}/database/key:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: issueOwnerRecordsKey
      description: Rotate the Records bearer key under the current owner session. The key is returned once and expires after 30 days. Captured current session/owner/account/store proof and the exact newly stored credential are rechecked before return. Ownership, identity and account epoch changes revoke it permanently.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: New Records key and expiration
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectRecordsCredential' }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project, store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Store lifecycle or the newly issued credential changed before return }
        '503': { description: Current Records authorization, policy or database state could not be verified }
    delete:
      operationId: revokeOwnerRecordsKey
      description: Revoke the Records bearer key under the current owner session. Captured current owner/session/account and store lifecycle must still match.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Records key revoked
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [revoked]
                properties:
                  revoked: { const: true }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project, store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Captured store lifecycle changed }
        '503': { description: Current Records authorization, policy or database state could not be verified }
  /api/projects/{projectId}/database/export:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportOwnerRecordsDatabase
      description: Download all retained Records from the captured current store, including an empty store. Current owner/session/account/pilot/identity/epoch and store lifecycle are rechecked before private data is returned. This owner export is separate from metered runtime record attempts and grants no recovery or billing authority.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Current Records snapshot, which may contain zero records
          headers:
            Content-Disposition:
              schema: { type: string, const: 'attachment; filename="stackr-database.json"' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RecordsExport' }
        '401': { description: Current owner session required }
        '404': { description: Project, store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Captured store lifecycle changed }
        '503': { description: Complete bounded Records contents or current authorization could not be verified }
  /api/projects/{projectId}/database/restore-preview:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: previewRecordsRestore
      description: Review a nonempty uploaded Records export without overwriting records. JSON is bounded to 1000000 bytes, depth 24 and 1000000 structural tokens with a five-second read deadline. Preview proof binds the captured owner/access epoch, store generation, current SQL UTC month and inventory; private proof fields are not exposed. Changed authority or store lifecycle requires a fresh owner review.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecordsSnapshot' }
      responses:
        '200': { $ref: '#/components/responses/RecordsRestorePreview' }
        '400': { description: Invalid Stackr Records snapshot }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project or Records database unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Captured Records store lifecycle changed; review again }
        '413': { description: JSON body exceeds 1000000 bytes }
        '415': { description: application/json Content-Type required }
        '503': { description: Current authority, bounded inventory or valid nonfuture usage could not be verified }
  /api/projects/{projectId}/database/restore-backup-preview:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: previewScheduledRecordsRestore
      description: Review a retained backup from the same project under the current owner session. The selection body is bounded to 512 bytes, depth 24 and 512 structural tokens with a five-second deadline. Preview proof also binds the original access epoch, destination store generation and exact retained snapshot identity. Current store/account/ownership changes require a fresh preview.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ScheduledRecordsSnapshot' }
      responses:
        '200': { $ref: '#/components/responses/RecordsRestorePreview' }
        '400': { description: Invalid or empty backup }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Backup or destination Records store unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Captured Records store lifecycle changed; review again }
        '413': { description: Selection body exceeds 512 bytes }
        '415': { description: application/json Content-Type required }
        '503': { description: Current authority, safe snapshot/inventory or valid nonfuture usage could not be verified }
  /api/projects/{projectId}/database/restore-backup:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: applyScheduledRecordsRestore
      description: Insert a reviewed retained backup into the same project's Records after explicit owner confirmation. Selection JSON is bounded to 512 bytes, depth 24 and 512 structural tokens with a five-second deadline. Original authority, destination generation, inventory/month and exact source snapshot are checked in the write transaction and before return. Restore is insert-only and charges one operation per inserted record; the destination name/key and retained backup remain unchanged.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ScheduledRecordsSnapshot'
                - type: object
                  required: [previewToken]
                  properties:
                    previewToken: { type: string, pattern: '^[a-f0-9]{64}$' }
      responses:
        '201': { $ref: '#/components/responses/RecordsRestoreResult' }
        '400': { description: Invalid backup selection, preview token or nonempty snapshot }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Backup or destination Records store unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Authority/store/source snapshot changed or review is stale; restore_changed retains its existing error and code shape }
        '413': { description: Selection body exceeds 512 bytes }
        '415': { description: application/json Content-Type required }
        '503': { description: Current authority, safe snapshot/inventory or valid nonfuture usage could not be verified }
  /api/projects/{projectId}/database/restore:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: applyRecordsRestore
      description: Insert a nonempty reviewed snapshot after explicit owner confirmation without overwriting existing records. JSON is bounded to 1000256 bytes, depth 24 and 1000256 structural tokens with a five-second deadline. The captured owner/access epoch, store generation, SQL UTC month and inventory are rechecked atomically and before return. Visible-state ABA and delete/recreate require fresh review. Destination name/key are preserved; one operation is charged per inserted record.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [snapshot, previewToken]
              properties:
                snapshot: { $ref: '#/components/schemas/RecordsSnapshot' }
                previewToken: { type: string, pattern: '^[a-f0-9]{64}$' }
      responses:
        '201': { $ref: '#/components/responses/RecordsRestoreResult' }
        '400': { description: Invalid restore request }
        '401': { description: Current owner session required }
        '403': { description: Invalid browser request origin }
        '404': { description: Project or Records database unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Preview/store/inventory changed or restore no longer fits; restore_changed retains its existing error and code shape }
        '413': { description: JSON body exceeds 1000256 bytes }
        '415': { description: application/json Content-Type required }
        '503': { description: Current authority, safe inventory or valid nonfuture usage could not be verified }
  /api/workspace:
    get:
      operationId: bootstrapWorkspace
      description: Load sign-in capabilities, the current session, and the projects owned by that session in one request.
      security: [{}, { OwnerSession: [] }]
      responses:
        '200': { description: Workspace capabilities, session user or null, and owned projects }
  /api/github/connection:
    get:
      operationId: getGitHubAppConnection
      description: Read GitHub connection availability and the linked account, when authorized.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Availability, connected status, and linked account summary }
        '401': { description: Stackr owner sign-in required }
        '503': { description: Connection state temporarily unavailable }
    delete:
      operationId: disconnectGitHubApp
      description: Remove the saved GitHub connection from all Stackr sessions for the signed-in user.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Connection removed }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin does not match the Stackr request origin }
        '503': { description: GitHub App or connection storage unavailable }
  /api/project-queues/{projectId}/{action}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: action
        required: true
        schema: { type: string, enum: [enqueue, claim, ack, retry, heartbeat] }
    post:
      operationId: operateProjectQueue
      description: Submit or lease a JSON job, extend an active lease, or finish a job. Producer tokens are limited to enqueue. Current project ownership, identity, account policy and token expiry are checked after the body and before returning private results. Ownership, identity and account changes revoke worker and producer tokens; restoring earlier state does not reactivate them. JSON is limited to 9000 bytes, depth 16 and 4096 structural tokens, with a five-second body-read deadline. Admission consumes the daily allowance before body validation, including invalid, timed-out and subsequently unauthorized requests. Heartbeats cannot extend past leaseLimitAt. For an empty claim, wait for the Retry-After interval.
      security: [{ ProjectQueueToken: [] }, { ProjectQueueProducerToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                queue: { type: string, default: default, maxLength: 32 }
                payload: { description: JSON payload for enqueue, up to 8 KiB }
                idempotencyKey: { type: string, maxLength: 128 }
                leaseSeconds: { type: integer, minimum: 10, maximum: 300 }
                id: { type: string, format: uuid }
                leaseToken: { type: string, description: Claim response token for ack, retry or heartbeat }
                expectedLeaseUntil: { type: integer, minimum: 1, description: Required for heartbeat. Pass leaseUntil from the last claim or heartbeat in Unix milliseconds. }
                delaySeconds: { type: integer, minimum: 0, maximum: 3600 }
      responses:
        '200': { description: Job state, claim result, or existing idempotent submission }
        '201': { description: New job queued }
        '400': { description: Invalid JSON, UTF-8, body length or structure, or invalid operation input }
        '401': { description: Missing, invalid, expired or revoked queue token, or captured project authorization no longer current }
        '408': { description: Request body aborted or its five-second read deadline exceeded }
        '409': { description: Job lease stale, queue at capacity, or idempotency conflict }
        '413': { description: Request body exceeds 9000 bytes }
        '415': { description: application/json Content-Type required }
        '429': { description: Daily queue operation limit reached }
        '503': { description: Current queue authorization or storage could not be verified }
  /api/projects/{projectId}/queues:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readProjectQueues
      description: Read retained per-queue counts, current ready wait and next delayed job alongside project-wide totals and token expirations. Current owner session, account policy and project authorization are rechecked before returning private metadata.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Current queue status and recent job metadata }
        '404': { description: Project or captured owner authorization unavailable }
        '503': { description: Current queue authorization or storage could not be verified }
  /api/projects/{projectId}/queues/producer-token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: issueProjectQueueProducerToken
      description: Issue a new enqueue-only credential under current owner authorization. Ownership, identity and account changes revoke it; restoring earlier state does not reactivate it.
      security: [{ OwnerSession: [] }]
      responses:
        '201': { description: New enqueue-only token and expiresAt timestamp. The token is returned once. }
        '404': { description: Project or captured owner authorization unavailable }
        '503': { description: Current queue authorization or storage could not be verified }
    delete:
      operationId: revokeProjectQueueProducerToken
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Producer token revoked }
        '404': { description: Project or captured owner authorization unavailable }
        '503': { description: Current queue authorization or storage could not be verified }
  /api/projects/{projectId}/queues/dead-letter:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listFailedProjectJobs
      security: [{ OwnerSession: [] }]
      parameters:
        - in: query
          name: before
          schema: { type: string }
          description: Opaque cursor returned as nextCursor from the previous page.
      responses:
        '200': { description: Up to 25 retained failed jobs and nextCursor. Entries include canRedrive and replacement linkage. }
        '400': { description: Invalid cursor }
        '404': { description: Project unavailable }
  /api/projects/{projectId}/queues/redrive:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: redriveFailedProjectJob
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, format: uuid }
      responses:
        '200': { description: Existing replacement job with duplicate true }
        '201': { description: New replacement job with redrivenFrom and duplicate false }
        '404': { description: Project or retained job unavailable }
        '409': { description: Job cannot be requeued or storage is at capacity }
        '429': { description: Daily queue operation limit reached }
  /api/projects/{projectId}/queues/cancel:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: cancelProjectJob
      description: Cancel a queued job before its first claim and keep its history for up to 24 hours.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id]
              properties:
                id: { type: string, format: uuid }
      responses:
        '200': { description: Job ID, cancelled state, cancelledAt timestamp and duplicate flag }
        '404': { description: Project or job unavailable }
        '409': { description: Job has been claimed or is already terminal }
        '429': { description: Daily queue operation limit reached }
  /api/projects/{projectId}/events:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectEventTopics
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Topics, consumer groups, quotas and token expiry }
        '404': { description: Project unavailable }
  /api/projects/{projectId}/events/topics:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    delete:
      operationId: removeProjectEventTopic
      description: Remove a topic after its groups and retained events are gone. The topic name stays reserved.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic]
              properties:
                topic: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
      responses:
        '200': { description: Topic removed }
        '404': { description: Project or topic unavailable }
        '409': { description: Topic has consumer groups or retained events }
        '429': { description: Daily operation limit reached }
  /api/projects/{projectId}/events/groups:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    delete:
      operationId: removeProjectEventGroup
      description: Remove a group and its saved position. Its name stays reserved within the topic.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, group]
              properties:
                topic: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                group: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
      responses:
        '200': { description: Group removed }
        '404': { description: Project or group unavailable }
        '429': { description: Daily operation limit reached }
  /api/project-events/{projectId}/publish:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: publishProjectEvent
      security: [{ ProjectEventProducerToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, payload]
              properties:
                topic: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                payload: { description: JSON payload up to 8 KiB }
                idempotencyKey: { type: string, maxLength: 128 }
      responses:
        '200': { description: Duplicate submission with original offset }
        '201': { description: Event appended }
        '401': { description: Producer token unavailable }
        '409': { description: Idempotency or storage conflict }
        '429': { description: Daily operations cap reached }
  /api/project-events/{projectId}/read:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: readProjectEvents
      security: [{ ProjectEventConsumerToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, group]
              properties:
                topic: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                group: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                after: { type: integer, minimum: 0, description: Exclusive replay offset. Defaults to the group’s committed offset. }
                limit: { type: integer, minimum: 1, maximum: 20 }
      responses:
        '200': { description: Retained events in offset order and the next offset }
        '401': { description: Consumer token unavailable }
        '409': { description: Offset is outside the available history }
        '429': { description: Daily operations cap reached }
  /api/project-events/{projectId}/commit:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: commitProjectEventOffset
      security: [{ ProjectEventConsumerToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [topic, group, expectedOffset, offset]
              properties:
                topic: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                group: { type: string, pattern: '^[a-z][a-z0-9-]{0,31}$' }
                expectedOffset: { type: integer, minimum: 0 }
                offset: { type: integer, minimum: 1 }
      responses:
        '200': { description: Committed group offset }
        '401': { description: Consumer token unavailable }
        '409': { description: Offset changed or could not be advanced }
        '429': { description: Daily operations cap reached }
  /api/deployments:
    get:
      operationId: listWorkspaceDeployments
      description: List deployments across projects in the signed-in workspace.
      security: [{ OwnerSession: [] }]
      parameters:
        - in: query
          name: project
          schema: { type: string, format: uuid }
        - in: query
          name: state
          schema: { type: string, enum: [live, ready, paused, failed] }
        - in: query
          name: runtime
          schema: { type: string, enum: [starter, static, javascript, container, service] }
        - in: query
          name: q
          description: Literal substring of the project name, address slug, release ID, tag, or Git commit. Whitespace is trimmed.
          schema: { type: string, minLength: 1, maxLength: 80 }
        - in: query
          name: cursor
          description: Opaque cursor from the preceding page with the same filters.
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 50, default: 25 }
      responses:
        '200': { description: Deployment summaries and a cursor for the next page }
        '400': { description: Invalid filters or cursor }
        '401': { description: Stackr sign-in required }
        '404': { description: The specified project is unavailable }
  /api/projects/{projectId}/deployments/{deploymentId}/details:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: deploymentId
        required: true
        schema: { type: string, format: uuid }
    get:
      operationId: getDeploymentDetails
      description: Inspect a retained release, its provenance and up to 20 recent activity events. Static releases include the file manifest, artifact digest and copiedFrom when applicable. The project view includes releaseGeneration and hasActiveTrafficSplit for guarded publication.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Project and release metadata }
        '401': { description: Stackr sign-in required }
        '404': { description: The project or release is unavailable }
  /api/projects/{projectId}/deployments/{deploymentId}/copy:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - { name: deploymentId, in: path, required: true, schema: { type: string, format: uuid } }
    post:
      operationId: copyOwnedStaticRelease
      description: Stage a private copy of an owned static release. A new tag is optional.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StaticReleaseCopyOptions' }
      responses:
        '200': { $ref: '#/components/responses/StaticReleaseCopyReceipt' }
        '201': { $ref: '#/components/responses/StaticReleaseCopyReceipt' }
        '400': { description: Invalid tag or operation ID }
        '401': { description: Stackr sign-in required }
        '403': { description: Request origin rejected }
        '404': { description: Source release unavailable }
        '409': { description: Release cannot be copied, tag or operation conflicts, or project capacity reached }
  /api/projects/{projectId}/release-approvals:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getReleaseApprovalPolicy
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/ReleaseApprovalPolicy' }
    put:
      operationId: saveReleaseApprovalPolicy
      description: Change the required owner approval setting with its current revision.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReleaseApprovalPolicy' }
      responses:
        '200': { $ref: '#/components/responses/ReleaseApprovalPolicy' }
        '409': { description: Stale policy revision or active traffic split }
  /api/projects/{projectId}/deployments/{deploymentId}/approval:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - { name: deploymentId, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      operationId: getReleaseApproval
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/ReleaseApproval' }
        '404': { description: Release unavailable }
    put:
      operationId: approveRelease
      security: [{ OwnerSession: [] }]
      requestBody:
        $ref: '#/components/requestBodies/ReleaseApprovalRevision'
      responses:
        '200': { $ref: '#/components/responses/ReleaseApproval' }
        '409': { description: Policy revision changed or the release is ineligible }
    delete:
      operationId: revokeReleaseApproval
      security: [{ OwnerSession: [] }]
      requestBody:
        $ref: '#/components/requestBodies/ReleaseApprovalRevision'
      responses:
        '200': { $ref: '#/components/responses/ReleaseApproval' }
        '409': { description: Policy revision changed or the release is receiving split traffic }
  /api/projects/{projectId}/activate-release:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: activateOwnedRelease
      description: Publish, restore, or resume an owned release. For browser requests send the Stackr Origin. Supply the generation and split status observed on the details page to reject a stale confirmation.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [deploymentId]
              properties:
                deploymentId: { type: string, format: uuid }
                expectedGeneration: { type: integer, minimum: 0, maximum: 9007199254740991 }
                expectedTrafficSplit: { type: boolean, description: Optional if expectedGeneration is provided }
                expectedRolloutRevision:
                  type: string
                  pattern: '^[a-f0-9]{32}$'
                  description: To finish a staged rollout, provide its final revision, current generation, and candidate deployment ID. Supply this field separately from expectedTrafficSplit.
      responses:
        '200': { description: The selected release was activated }
        '400': { description: Invalid release or publication precondition }
        '401': { description: Stackr sign-in required }
        '403': { description: Invalid request origin }
        '404': { description: The project is unavailable }
        '409': { description: The release is blocked or the project changed. A stale confirmation returns code release_changed. }
  /api/projects/{projectId}/database-migrations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listDatabaseMigrationTargets
      description: Read supported targets and local dedicated SQLite availability. Captured project owner, current session/account/pilot policy and project authorization epoch are rechecked before returning private metadata. This inspection makes no provider request.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Supported targets and dedicated SQLite availability }
        '404': { description: Project or captured current owner authorization unavailable }
        '503': { description: Current authorization or database metadata could not be verified }
    post:
      operationId: reviewOrApplyDatabaseMigration
      security: [{ OwnerSession: [] }]
      description: Review SQL before applying it. Only provisioned dedicated SQLite applies on Stackr, after the reviewed digest and fresh billing enrollment are checked. PostgreSQL-family targets return a credential-free local psql bundle without provider execution. The owner is captured before reading the body; captured owner/session/account/pilot/epoch are rechecked after the body and before final plan or script disclosure. Apply rechecks current billing enrollment before every actual D1 request. JSON is limited to 131072 bytes, depth 8 and 4096 structural tokens with a five-second body-read deadline; SQL remains limited to 65536 UTF-8 bytes. A recovered version receipt after a lost acknowledgement can establish a committed transaction while usage remains unknown; this returns 502 without rows or applied-success data and blocks retries through sticky SQL usage uncertainty until explicit operator reconciliation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action, target, version, sql]
              properties:
                action: { type: string, enum: [plan, apply] }
                target: { type: string, enum: [d1, postgresql, supabase, neon] }
                version: { type: string, maxLength: 80 }
                sql: { type: string, maxLength: 65536, description: At most 65536 UTF-8 bytes. Dedicated SQLite accepts up to 24 supported statements of at most 16384 bytes each. }
                digest: { type: string, description: Required to apply a reviewed dedicated SQLite migration }
      responses:
        '200': { description: Reviewed migration or applied version with verified provider usage }
        '400': { description: Invalid migration input, JSON, UTF-8, body length or structure }
        '403': { description: Invalid browser origin or the workspace cannot apply migrations to its database }
        '404': { description: Project or captured current owner authorization unavailable }
        '408': { description: Request body aborted or its five-second read deadline exceeded }
        '409': { description: The review digest or migration version conflicts }
        '413': { description: JSON request body exceeds 131072 bytes }
        '422': { description: Provider rejected the SQLite migration; usage can still require reconciliation }
        '429': { description: SQL allowance exhausted or sticky provider usage uncertainty requires reconciliation }
        '502': { description: Migration outcome or usage unconfirmed, including a recovered committed receipt with unknown usage; no applied-success data or rollback claim }
        '503': { description: Current authorization, database service or provider unavailable }
  /api/projects/{projectId}/databases/supabase/manage:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getSupabaseBackendTarget
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Hosted Supabase connection and function source limit }
    post:
      operationId: manageSupabaseBackend
      description: Read safe Auth and function metadata, change signup policy, or review and deploy a TypeScript function to the connected project.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action, target]
              properties:
                action: { type: string, enum: [inspect, signup, plan-function, deploy-function] }
                target: { type: string, description: Connected Supabase project reference }
                token: { type: string, format: password, writeOnly: true, description: Management API token required except when reviewing a function }
                confirm: { type: boolean, description: Required for signup changes and function deployment }
                signupEnabled: { type: boolean }
                slug: { type: string }
                source: { type: string, maxLength: 65536 }
                verifyJwt: { type: boolean }
                digest: { type: string, description: Required for function deployment }
      responses:
        '200': { description: Backend metadata, verified signup policy, or function review }
        '201': { description: Supabase confirmed the deployed function and JWT setting }
        '409': { description: Target changed, connection required, or function review is stale }
  /api/projects/{projectId}/analytics:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: query
        name: hours
        schema: { type: integer, minimum: 1, maximum: 168, default: 24 }
    get:
      operationId: getProjectAnalytics
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Recorded request counts and hourly analytics }
  /api/projects/{projectId}/logs:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: query
        name: minutes
        schema: { type: integer, minimum: 1, maximum: 1440, default: 60 }
      - in: query
        name: limit
        schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
      - in: query
        name: after
        description: Start at 0 for export and use nextCursor to resume
        schema: { type: string }
      - in: query
        name: before
        description: Use olderCursor from the preceding newest-first page with the same filters and window.
        schema: { type: string }
      - in: query
        name: status
        schema: { type: string, enum: [1xx, 2xx, 3xx, 4xx, 5xx] }
      - in: query
        name: runtime
        schema: { type: string, enum: [starter, static, javascript, container] }
      - in: query
        name: method
        schema: { type: string, enum: [GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, OTHER] }
      - in: query
        name: minLatencyMs
        schema: { type: integer, minimum: 0, maximum: 60000 }
      - in: query
        name: releaseId
        description: Filter to the successful release selected for the request. Use the same filter when resuming older-page cursors.
        schema: { type: string, format: uuid }
      - in: query
        name: requestId
        description: Exact X-Stackr-Request-ID value. Use without cursors or other filters except the time window.
        schema: { type: string, pattern: '^[a-f0-9]{32}$' }
    get:
      operationId: getProjectRequestLogs
      security: [{ OwnerSession: [] }, { ProjectLogToken: [] }]
      responses:
        '200': { description: Sanitized project events with a nullable releaseId and pagination cursors where applicable }
        '400': { description: Invalid filter or cursor }
        '401': { description: Sign in or use an active project log token }
  /api/projects/{projectId}/logs/token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectLogTokenStatus
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Log export availability and token expiry }
    post:
      operationId: createProjectLogToken
      security: [{ OwnerSession: [] }]
      responses:
        '201': { description: New read-only token shown once }
    delete:
      operationId: revokeProjectLogToken
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Project log token revoked }
  /api/projects/{projectId}/alerts/feed:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: query
        name: after
        description: Pass nextCursor from the last processed page. Omit for retained history.
        schema: { type: string }
      - in: query
        name: limit
        schema: { type: integer, minimum: 1, maximum: 100 }
    get:
      operationId: getProjectAlertFeed
      security: [{ OwnerSession: [] }, { ProjectAlertFeedToken: [] }]
      responses:
        '200': { description: Opening and resolution events with nextCursor and hasMore }
        '400': { description: Invalid limit or cursor }
        '401': { description: Sign in or use an active project alert feed token }
        '404': { description: Project unavailable }
  /api/projects/{projectId}/alerts/feed/token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProjectAlertFeedTokenStatus
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Feed availability and token expiry }
    post:
      operationId: createProjectAlertFeedToken
      security: [{ OwnerSession: [] }]
      responses:
        '201': { description: New read-only token shown once }
    delete:
      operationId: revokeProjectAlertFeedToken
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Project alert feed token revoked }
  /api/projects/{projectId}/deployments/{deploymentId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: deploymentId
        required: true
        schema: { type: string, format: uuid }
    delete:
      operationId: removeUnusedRelease
      description: Delete a managed release and its stored files. The browser must send the Stackr origin. Releases in use for production, an active canary, or a named preview are protected.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Release removed
          content:
            application/json:
              schema:
                type: object
                required: [removed, deploymentId]
                properties:
                  removed: { const: true }
                  deploymentId: { type: string, format: uuid }
        '401':
          description: Sign in required
        '403':
          description: Invalid request origin
        '404':
          description: Project or release not found
        '409':
          description: Release is in use or cannot be removed from Stackr
  /api/projects/{projectId}/git-import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: discoverGitRepositories
      description: Browse repository metadata for the selected provider. The browser must send the Stackr origin. Each lookup uses the supplied credential for one request. Link the repository separately after review.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, token]
              properties:
                provider: { type: string, enum: [github, gitlab, bitbucket] }
                token: { type: string, format: password, minLength: 16, maxLength: 514, writeOnly: true }
                page: { type: integer, minimum: 1, maximum: 50, default: 1 }
                search: { type: string, maxLength: 80, description: Repository name filter. GitHub filters the current page. }
                workspace: { type: string, maxLength: 100, description: Required Bitbucket Cloud workspace slug }
                email: { type: string, format: email, maxLength: 254, writeOnly: true, description: Required Atlassian email for Bitbucket Cloud }
              if:
                properties:
                  provider: { const: bitbucket }
              then:
                required: [workspace, email]
      responses:
        '200':
          description: A page of repository metadata with an optional next page number.
          content:
            application/json:
              schema:
                type: object
                required: [provider, repositories, page, nextPage]
                properties:
                  provider: { type: string, enum: [github, gitlab, bitbucket] }
                  repositories:
                    type: array
                    maxItems: 20
                    items:
                      type: object
                      required: [path, url, visibility, defaultBranch]
                      properties:
                        path: { type: string }
                        url: { type: string, format: uri }
                        visibility: { type: string, enum: [private, internal, public, unknown] }
                        defaultBranch: { type: [string, 'null'] }
                  page: { type: integer, minimum: 1, maximum: 50 }
                  nextPage: { type: [integer, 'null'], minimum: 2, maximum: 50 }
        '400': { description: Invalid provider, credential, or pagination fields }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin or provider access rejected }
        '404': { description: Project or Bitbucket workspace inaccessible }
        '415': { description: JSON request body required }
        '429': { description: Repository provider rate limit reached }
        '502': { description: Repository provider unavailable }
  /api/projects/{projectId}/vercel-import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: previewVercelImport
      description: Read a Vercel project's build settings, Git link, and domain inventory for review. The browser must send the Stackr origin. The supplied Vercel access token is used only for this lookup.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [project, token]
              properties:
                project: { type: string, maxLength: 100, description: Vercel project name or ID }
                teamId: { type: string, maxLength: 100, description: Vercel team ID when needed }
                token: { type: string, format: password, minLength: 16, maxLength: 514, writeOnly: true }
      responses:
        '200':
          description: Vercel settings for review. Domain lookup can report unavailable separately.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HostingImportReview' }
        '400': { description: Invalid Vercel project, team or token fields }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin or Vercel access rejected }
        '404': { description: Project inaccessible in Stackr or Vercel }
        '415': { description: JSON request body required }
        '429': { description: Vercel rate limit reached }
        '502': { description: Vercel settings unavailable }
  /api/projects/{projectId}/hosting-import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: previewHostingImport
      description: Review a Netlify or Cloudflare Pages project before staging its static build. Stackr uses the source token for this request. The same-origin owner session is required.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, project, token]
              properties:
                provider: { type: string, enum: [netlify, cloudflare-pages] }
                project: { type: string, maxLength: 63, description: Netlify site UUID or Cloudflare Pages project name }
                accountId: { type: string, pattern: '^[a-fA-F0-9]{32}$', description: Cloudflare account ID for a Pages project }
                token: { type: string, format: password, minLength: 16, maxLength: 514, writeOnly: true }
              if:
                properties:
                  provider: { const: cloudflare-pages }
              then:
                required: [accountId]
      responses:
        '200':
          description: Reviewed metadata and migration checks
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HostingImportReview' }
        '400': { description: Invalid provider, project, account, or token input }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin or provider access rejected }
        '404': { description: Project inaccessible in Stackr or the selected provider }
        '415': { description: JSON request body required }
        '429': { description: Provider lookup rate limit reached }
        '502': { description: Provider settings unavailable }
        '503': { description: Project lookup capacity temporarily unavailable }
  /api/projects/{projectId}/routing-import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: reviewRoutingImport
      description: Review supported redirects, rewrites, and security headers without changing project settings. The response includes an optional revision-guarded request body for each rules endpoint.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  additionalProperties: false
                  required: [format, config]
                  properties:
                    format: { const: vercel }
                    config: { type: string, description: Contents of vercel.json in UTF-8, up to 16 KiB }
                - type: object
                  additionalProperties: false
                  required: [format]
                  anyOf:
                    - required: [redirects]
                    - required: [headers]
                  properties:
                    format: { enum: [netlify, cloudflare-pages] }
                    redirects: { type: string, description: Contents of _redirects in UTF-8, up to 16 KiB }
                    headers: { type: string, description: Contents of _headers in UTF-8, up to 16 KiB }
      responses:
        '200':
          description: Compatible additions and source-specific review notes. Apply changes through the corresponding existing rules endpoint.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingImportReview' }
        '400': { description: Invalid format, content, or file size }
        '401': { description: Project owner sign-in required }
        '403': { description: Same-origin request required }
        '404': { description: Project not found }
        '409': { description: Saved routing settings could not be reviewed }
        '415': { description: JSON request body required }
  /api/projects/{projectId}/routing-import/test:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: testRoutingImport
      description: Model public static GET routing on one owned release. Include optional revision-checked draft rules to compare them with saved settings. The check reads file metadata and project settings.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [deploymentId, paths]
              properties:
                deploymentId: { type: string, format: uuid }
                paths:
                  type: array
                  minItems: 1
                  maxItems: 20
                  items: { type: string, maxLength: 242, description: App-relative path without a query string or fragment }
                changes:
                  $ref: '#/components/schemas/RoutingImportReview/properties/changes'
      responses:
        '200':
          description: Predicted outcomes for saved or proposed rules
          content:
            application/json:
              schema:
                type: object
                required: [deploymentId, comparedWithSaved, results]
                properties:
                  deploymentId: { type: string, format: uuid }
                  comparedWithSaved: { type: boolean }
                  results:
                    type: array
                    maxItems: 20
                    items: { $ref: '#/components/schemas/StaticRouteTestResult' }
                  savedResults:
                    type: array
                    maxItems: 20
                    items: { $ref: '#/components/schemas/StaticRouteTestResult' }
        '400': { description: Invalid paths, release ID, or rule proposal }
        '401': { description: Project owner sign-in required }
        '403': { description: Same-origin request required }
        '404': { description: Release unavailable in the project }
        '409': { description: Stale rules or unavailable static artifact }
        '415': { description: JSON request body required }
  /api/git/branches:
    post:
      operationId: listConnectedGitBranches
      description: Browse a repository through a saved GitHub, GitLab.com or Bitbucket Cloud connection, or a GitHub App grant.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/GitBranchLookup'
                - type: object
                  properties:
                    githubApp:
                      type: object
                      required: [installationId, repositoryId]
                      properties:
                        installationId: { type: integer, minimum: 1 }
                        repositoryId: { type: integer, minimum: 1 }
                        page: { type: integer, minimum: 1, maximum: 9999, default: 1 }
      responses:
        '200': { $ref: '#/components/responses/GitBranchPage' }
        '400': { description: Invalid repository or page }
        '401': { description: Stackr session or GitHub authorization required }
        '403': { description: Origin or repository access rejected }
        '404': { description: Repository or connection unavailable }
        '429': { description: Git lookup allowance reached }
        '502': { description: Git provider could not return the branch list }
  /api/git/public-branches:
    post:
      operationId: listPublicGitHubBranches
      description: Browse a public GitHub repository without a repository credential. A Stackr owner session is required.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GitBranchLookup' }
      responses:
        '200': { $ref: '#/components/responses/GitBranchPage' }
        '400': { description: Invalid GitHub repository or page }
        '401': { description: Stackr session required }
        '403': { description: Origin rejected }
        '404': { description: Public repository unavailable }
        '413': { description: The public repository advertises more refs than Stackr can list }
        '429': { description: Git lookup allowance reached }
        '502': { description: GitHub could not return the branch list }
  /api/git/inspect:
    post:
      operationId: inspectGitRepository
      description: Read repository metadata at an exact commit using the owner's saved Git connection or GitHub App grant and suggest build settings.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [repositoryUrl]
              properties:
                repositoryUrl: { type: string, format: uri }
                ref: { type: string, maxLength: 100, description: Branch name. Defaults to the repository's default branch. }
                rootDirectory: { type: string, maxLength: 160, default: '.', description: App directory inside the repository }
                githubApp:
                  type: object
                  required: [installationId, repositoryId]
                  properties:
                    installationId: { type: integer, minimum: 1 }
                    repositoryId: { type: integer, minimum: 1 }
                    page: { type: integer, minimum: 1, maximum: 9999, default: 1 }
      responses:
        '200': { description: Repository, inspected commit, detected framework, suggested build settings and a staticDirectory hint when a dedicated directory contains index.html }
        '400': { description: Invalid repository, branch or directory }
        '401': { description: Stackr sign-in required }
        '403': { description: Origin or provider access rejected }
        '404': { description: Connection or repository unavailable }
        '429': { description: Git lookup rate limit reached }
        '502': { description: Repository inspection failed }
  /api/projects/{projectId}/deploy-hooks:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listProjectDeployHooks
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Hook metadata, last outcome, limits, and available source options. Invocation URLs are excluded. }
        '401': { description: Stackr sign-in required }
        '404': { description: Project not found }
    post:
      operationId: createProjectDeployHook
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, kind, ref]
              additionalProperties: false
              properties:
                name: { type: string, minLength: 1, maxLength: 48 }
                kind: { type: string, enum: [directory, static, starter] }
                ref: { type: string, maxLength: 128, description: Git branch or immutable commit SHA }
                rootDirectory: { type: string, description: Required for public GitHub directory hooks only }
                spa: { type: boolean, description: Enable SPA routing for directory or static ZIP sources }
      responses:
        '201': { description: Hook created. The response contains its invocation URL once. Treat the URL as a credential. }
        '400': { description: Invalid hook settings }
        '401': { description: Stackr sign-in required }
        '403': { description: Same-origin request required }
        '404': { description: Project not found }
        '409': { description: Repository or saved connection unavailable, duplicate name, or hook capacity reached }
  /api/projects/{projectId}/deploy-hooks/{hookId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: hookId
        required: true
        schema: { type: string, format: uuid }
    delete:
      operationId: revokeProjectDeployHook
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Invocation URL revoked }
        '401': { description: Stackr sign-in required }
        '403': { description: Same-origin request required }
        '404': { description: Project or hook not found }
  /api/deploy-hooks/{hookToken}:
    parameters:
      - in: path
        name: hookToken
        required: true
        schema: { type: string, pattern: '^sdh_[A-Za-z0-9_-]{43}$' }
        description: Secret from the one-time invocation URL. Keep out of logs and public content.
    post:
      operationId: invokeProjectDeployHook
      security: []
      description: Send a server-to-server POST without a query, body, Origin, Cookie or Authorization header to stage a private release.
      responses:
        '201': { description: A private release was staged. Returns deploymentId, active false, and commit. }
        '404': { description: Hook unavailable or revoked }
        '409': { description: Saved Git connection or release admission changed }
        '429': { description: Hook cooldown or staging limits reached }
        '503': { description: Unavailable or outcome unknown. Check Deployments before retrying. }
  /api/projects/{projectId}/git-artifact:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: stageGitArtifact
      description: Stage a linked repository's dedicated static directory or a committed prepared artifact as a private preview. Use the canonical Stackr origin with an owner session.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [kind]
              properties:
                kind: { type: string, enum: [directory, static, starter] }
                ref: { type: string, maxLength: 128, description: Branch or exact commit. Only public GitHub directory imports may omit it to use the default branch. }
                rootDirectory: { type: string, description: Required for directory imports. A dedicated relative path containing index.html. }
                publicRepository: { type: boolean, description: Use anonymous reads for a public GitHub directory. Omit when using a saved Git connection or GitHub App grant. }
                spa: { type: boolean, description: Enable SPA routing on a static site. }
                githubApp:
                  type: object
                  required: [installationId, repositoryId]
                  properties:
                    installationId: { type: integer, minimum: 1 }
                    repositoryId: { type: integer, minimum: 1 }
                    page: { type: integer, minimum: 1, maximum: 9999, default: 1 }
      responses:
        '200': { description: Managed starter staged for owner review }
        '201': { description: Static release staged with a deployment ID and resolved commit }
        '400': { description: Invalid source settings }
        '401': { description: Stackr session or GitHub grant required }
        '403': { description: Origin or repository access rejected }
        '404': { description: Project, connection or Git source unavailable }
        '409': { description: Project or connection changed, or release capacity reached }
        '413': { description: Static file limits exceeded }
        '422': { description: Directory or Git source cannot be staged directly }
        '429': { description: Git read allowance reached }
        '502': { description: Git source could not be read }
  /api/projects/{projectId}/build-workflow:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: generateBuildWorkflow
      description: Generate a repository CI workflow for a static site or a container image. Container staging uses a registered digest. The browser must send the Stackr origin.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider]
              properties:
                provider: { type: string, enum: [github, gitlab, bitbucket] }
                framework: { type: string, description: Uses the saved project preset when omitted, enum: [plain, vite, next-static, astro, svelte-static, nuxt-static, create-react-app, custom, node-container, python-container, go-container, rust-container, dockerfile] }
                branch: { type: string, maxLength: 100, default: main }
                githubPullRequestPreviews: { type: boolean, description: Also generate the two pull request preview workflows for a GitHub Actions static site. }
                prebuiltPreview: { type: boolean, description: Also generate a stage-only Bash script for a prebuilt static ZIP. }
                root: { type: string, maxLength: 519, default: '.', description: App directory or container build context }
                output: { type: [string, 'null'], maxLength: 519, description: Static output directory inside the app. Null uses the framework default. }
                installCommand: { type: [string, 'null'], description: Static build install command up to 1024 UTF-8 bytes. Null uses the preset and an empty string skips the step. }
                buildCommand: { type: [string, 'null'], description: Static build command up to 1024 UTF-8 bytes. Null uses the preset and an empty string skips the step. }
                environmentTarget: { type: [string, 'null'], enum: [production, preview, development, null], description: Optional Stackr variables for the static build job }
                spa: { type: boolean, description: Enable static single-page app fallback }
                dockerfile: { type: string, maxLength: 519, default: Dockerfile, description: Dockerfile path inside the context }
                instanceType: { type: string, enum: [lite, standard-1], default: lite }
                replicas: { type: integer, minimum: 1, maximum: 3, default: 1 }
                port: { type: integer, minimum: 1, maximum: 65535, default: 8080 }
      responses:
        '200':
          description: Generated workflow and optional Dockerfile template
          content:
            application/json:
              schema:
                type: object
                required: [filename, environment, workflow, root, requiredSecret]
                properties:
                  filename: { type: string }
                  environment: { type: string }
                  workflow: { type: string }
                  root: { type: string }
                  requiredSecret: { const: STACKR_DEPLOY_TOKEN }
                  prebuiltPreview:
                    type: object
                    required: [filename, requiredSecret, script]
                    properties:
                      filename: { const: stackr-stage-preview.sh }
                      requiredSecret: { const: STACKR_PREVIEW_TOKEN }
                      script: { type: string }
                  buildEnvironment:
                    type: object
                    properties:
                      name: { type: string }
                      target: { type: string, enum: [production, preview, development] }
                      requiredSecret: { const: STACKR_BUILD_ENV_TOKEN }
                  output: { type: string }
                  kind: { const: container }
                  dockerfilePath: { type: string }
                  dockerfile: { type: [string, 'null'] }
                  requiresImageRegistration: { const: true }
                  artifacts:
                    type: array
                    items: { type: string }
        '400': { description: Invalid build settings }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
        '503': { description: Canonical build endpoint unavailable }
  /api/projects/{projectId}/build-environment/{target}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: target
        required: true
        schema: { type: string, enum: [production, preview, development] }
    get:
      operationId: readBuildEnvironment
      description: Fetch decrypted variables in trusted CI for the token's project and environment. Keep the response out of logs.
      security: [{ BuildEnvironmentToken: [] }]
      responses:
        '200':
          description: Build variable values for one environment
          content:
            application/json:
              schema:
                type: object
                required: [target, variables]
                properties:
                  target: { type: string, enum: [production, preview, development] }
                  variables:
                    type: object
                    maxProperties: 24
                    additionalProperties: { type: string }
        '401': { description: Missing, revoked, expired or mismatched build token }
        '503': { description: Build environments unavailable }
  /api/flags/{projectId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readPublicFeatureFlags
      description: Read explicitly public feature flags for a project.
      security: []
      responses:
        '200':
          description: Opted-in boolean flags
          content:
            application/json:
              schema:
                type: object
                properties:
                  flags:
                    type: object
                    additionalProperties: { type: boolean }
        '404': { description: No public flags }
        '429': { description: Flag read limit reached }
  /api/projects/{projectId}/zogy-address:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readZogyAddress
      description: Read the current app address reservation and routing availability.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/ZogyAddress' }
        '401': { description: Stackr owner sign-in required }
        '404': { description: Project inaccessible }
    post:
      operationId: assignZogyAddress
      description: Reserve an automatically selected app address when the project has none. The browser must send the Stackr origin.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/ZogyAddress' }
        '201': { $ref: '#/components/responses/ZogyAddress' }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
        '409': { description: Address reservation unavailable }
        '503': { description: App address reservation is disabled }
    put:
      operationId: changeZogyAddress
      description: Choose an available app address. Renaming permanently retires the current name. The browser must send the Stackr origin.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [label]
              properties:
                label: { type: string, pattern: '^[a-z0-9][a-z0-9-]{3,38}[a-z0-9]$' }
      responses:
        '200': { $ref: '#/components/responses/ZogyAddress' }
        '201': { $ref: '#/components/responses/ZogyAddress' }
        '400': { description: Invalid name }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
        '409': { description: Name unavailable or admission limit reached }
        '503': { description: App address reservation is disabled }
    delete:
      operationId: retireZogyAddress
      description: Permanently retire the project's app address. The browser must send the Stackr origin.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/ZogyAddress' }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
  /api/projects/{projectId}/zogy:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: readZogyHandoff
      description: Read eligible Stackr origin hostnames and managed setup links for a Zo.gy load-balancer pool.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Origin readiness for the current project
          content:
            application/json:
              schema:
                type: object
                required: [status, origins, demoUrl, contactUrl, minOrigins, maxOrigins]
                properties:
                  status: { type: string, enum: [release_required, domains_unavailable, domain_required, managed_handoff] }
                  origins:
                    type: array
                    items: { type: string, format: uri }
                  demoUrl: { type: string, format: uri }
                  contactUrl: { type: string, format: uri }
                  minOrigins: { const: 2 }
                  maxOrigins: { const: 12 }
        '401': { description: Stackr owner sign-in required }
        '404': { description: Project inaccessible }
  /api/projects/{projectId}/managed-builds:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listManagedBuilds
      description: Read the managed runner's availability, linked GitHub repository, and recent project build history.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Build history and runner readiness
          content:
            application/json:
              schema:
                type: object
                required: [available, repository, builds]
                properties:
                  available: { type: boolean }
                  repository: { type: [string, 'null'], description: GitHub owner and repository name }
                  builds:
                    type: array
                    maxItems: 20
                    items:
                      type: object
                      required: [id, status, commit, preset, createdAt, deploymentId, failure]
                      properties:
                        id: { type: string, format: uuid }
                        status: { type: string, enum: [queued, building, staged, failed, cancelled] }
                        commit: { type: string, pattern: '^[a-f0-9]{40}$' }
                        preset: { type: string, enum: [plain, vite, node-static] }
                        createdAt: { type: integer, description: Unix time in milliseconds }
                        deploymentId: { type: [string, 'null'], format: uuid }
                        failure: { type: [string, 'null'] }
        '401': { description: Stackr owner sign-in required }
        '404': { description: Project inaccessible }
    post:
      operationId: queueManagedBuild
      description: Queue a pinned public GitHub commit for static staging. The browser must send the Stackr origin. Vite and Node presets use cached npm dependencies.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [commit, preset, root, output, spa]
              properties:
                commit: { type: string, pattern: '^[a-f0-9]{40}$' }
                preset: { type: string, enum: [plain, vite, node-static] }
                root: { type: string, maxLength: 519, description: App path relative to the repository or a single dot for the repository root }
                output: { type: string, maxLength: 519, description: Build output directory relative to the app path }
                spa: { type: boolean, description: Enable single-page app fallback }
      responses:
        '202':
          description: Build queued
          content:
            application/json:
              schema:
                type: object
                required: [id, status]
                properties:
                  id: { type: string, format: uuid }
                  status: { const: queued }
        '400': { description: Invalid build settings }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
        '409': { description: Build admission refused }
        '503': { description: Managed build runner unavailable }
  /api/projects/{projectId}/files/restore-preview:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: previewPrivateFileRestore
      description: Validate an exported snapshot and review an additive restore. Requires the owner session and Stackr origin; file tokens are unsupported. A valid preview counts as one daily file operation. The 7,100,000-byte JSON limit covers the pilot export envelope. Review and apply each require a validation attempt admitted before body processing, with 30 per owner and 300 per platform UTC day, one active per owner and three platform-wide. Upload deadline is 60 seconds; malformed and aborted submissions consume attempts.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PrivateFileSnapshot' }
      responses:
        '200':
          description: Review of integrity, conflicts, capacity and operations; empty or blocked snapshots have no usable review token
          content:
            application/json:
              schema:
                type: object
                required: [fileCount, totalBytes, currentFiles, currentBytes, remainingFiles, remainingBytes, conflicts, canRestore, reason, previewToken]
                properties:
                  fileCount: { type: integer, minimum: 0, maximum: 40 }
                  totalBytes: { type: integer, minimum: 0, maximum: 5242880 }
                  currentFiles: { type: integer, minimum: 0 }
                  currentBytes: { type: integer, minimum: 0 }
                  remainingFiles: { type: integer, minimum: 0 }
                  remainingBytes: { type: integer, minimum: 0 }
                  conflicts: { type: array, items: { type: string } }
                  canRestore: { type: boolean }
                  reason: { enum: [null, empty, conflicts, capacity, quota] }
                  previewToken: { type: [string, 'null'], description: Review binding valid for the same source, destination state and UTC date }
        '400': { description: Invalid snapshot or checksum }
        '401': { description: Owner sign-in required; file tokens are unsupported }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible or authorization changed }
        '405': { description: POST required }
        '413': { description: Snapshot exceeds encoded body, decoded file or storage limits }
        '415': { description: JSON required }
        '408': { description: Request upload deadline exceeded, aborted upload or expired validation }
        '429': { description: Validation slots, daily validation attempts or preview operation allowance exhausted }
  /api/projects/{projectId}/files/restore:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: restorePrivateFiles
      description: Apply a reviewed additive restore in one transaction. Existing keys are never overwritten. All restored files receive fresh revisions and update times. A successful restore counts one file operation per file. Owner, destination, capacity and operations are checked again at commit. No partial restore is retained on failure.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [snapshot, previewToken]
              properties:
                snapshot: { $ref: '#/components/schemas/PrivateFileSnapshot' }
                previewToken: { type: string, pattern: '^[a-f0-9]{64}$' }
      responses:
        '201':
          description: All reviewed files restored
          content:
            application/json:
              schema:
                type: object
                required: [restored, bytes]
                properties:
                  restored: { type: integer, minimum: 1, maximum: 40 }
                  bytes: { type: integer, minimum: 0, maximum: 5242880 }
        '400': { description: Invalid snapshot, checksum or review token }
        '401': { description: Owner sign-in required; file tokens are unsupported }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible or authorization changed }
        '405': { description: POST required }
        '409': { description: Source, destination, shared capacity or UTC date changed; review again }
        '413': { description: Snapshot exceeds encoded body, decoded file or storage limits }
        '415': { description: JSON required }
        '408': { description: Request upload deadline exceeded, aborted upload or expired validation }
        '429': { description: Validation slots, daily attempts or file operation allowance exhausted }
  /api/projects/{projectId}/files/export:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: exportPrivateProjectFiles
      description: Download one owner-authorized JSON snapshot of private project files, including base64 contents, revisions and SHA-256 checksums. The pilot limits are 40 files, 1 MiB per file and 5 MiB total. Counts as one daily file operation. Project file tokens cannot use this endpoint.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Private file export, including an empty snapshot for a project without files
          content:
            application/json:
              schema:
                type: object
                required: [format, version, fileCount, totalBytes, files]
                properties:
                  format: { const: stackr-private-files }
                  version: { const: 1 }
                  fileCount: { type: integer, minimum: 0, maximum: 40 }
                  totalBytes: { type: integer, minimum: 0, maximum: 5242880 }
                  files:
                    type: array
                    maxItems: 40
                    items:
                      type: object
                      required: [key, size, revision, etag, updatedAt, sha256, encoding, content]
                      properties:
                        key: { type: string, maxLength: 128 }
                        size: { type: integer, minimum: 0, maximum: 1048576 }
                        revision: { type: string, format: uuid }
                        etag: { type: string }
                        updatedAt: { type: integer, minimum: 0 }
                        sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
                        encoding: { const: base64 }
                        content: { type: string, contentEncoding: base64 }
        '401': { description: Owner sign-in required; file tokens are unsupported }
        '403': { description: Cross-site request rejected }
        '404': { description: Project inaccessible or authorization changed }
        '405': { description: GET required }
        '409': { description: Retained file snapshot is corrupt or exceeds pilot limits }
        '429': { description: Daily file operation allowance reached }
  /api/projects/{projectId}/managed-builds/{buildId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - in: path
        name: buildId
        required: true
        schema: { type: string, format: uuid }
    delete:
      operationId: cancelManagedBuild
      description: Cancel a queued or running project build and revoke its artifact staging lease. A running process may continue until exit or timeout; cancellation does not refund daily build admission. The browser must send the Stackr origin.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Build cancelled }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin rejected }
        '404': { description: Project inaccessible }
        '409': { description: Build unavailable for cancellation }
  /api/projects/{projectId}/ci-deploy/container:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: stageContainerRelease
      description: Stage a registered project image digest. Verify a paid health preview before promotion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [image, instanceType, replicas, port]
              properties:
                image: { type: string, description: Approved SHA-256 digest or complete immutable registry reference for this project }
                instanceType: { type: string, enum: [lite, standard-1] }
                replicas: { type: integer, minimum: 1, maximum: 3 }
                port: { type: integer, minimum: 1, maximum: 65535 }
                tag: { type: string, maxLength: 40 }
                commit: { type: string, pattern: '^[a-f0-9]{40}$' }
      responses:
        '201': { description: Staged release ID with active false }
        '401': { description: Invalid or expired deployment token }
        '409': { description: Release limit reached or project changed }
        '503': { description: Container hosting unavailable }
  /api/projects/{projectId}/ci-deploy/javascript:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: stageJavaScriptRelease
      description: Stage a bundled ES module when paid JavaScript hosting is available. The active release stays live until promotion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [source]
              properties:
                source: { type: string, maxLength: 32768, description: Bundled default fetch handler up to 32 KiB UTF-8 }
                tag: { type: string, maxLength: 40 }
                commit: { type: string, pattern: '^[a-f0-9]{40}$' }
      responses:
        '201': { description: Staged release ID with active false }
        '401': { description: Invalid or expired deployment token }
        '409': { description: Release limit reached or project changed }
        '503': { description: JavaScript hosting unavailable }
  /api/projects/{projectId}/schedules:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listSchedules
      description: Read schedules under a current owner session or exact scoped schedule key, with captured owner/identity/access-epoch, account/pilot/configuration and session/key SQL proof rechecked before private return. Applying prepared migration 0101 revokes legacy keys and pauses automatic backup jobs without deleting retained snapshots or usage.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      responses:
        '200': { description: Scheduled jobs and workspace limits }
        '401': { description: Invalid or expired schedule token }
        '404': { description: Project or current owner authorization unavailable }
        '503': { description: Current schedule authorization, policy or metadata could not be verified }
    post:
      operationId: createSchedule
      description: Create a UTC cron job under current captured owner/session or exact scoped schedule key. Webhooks start paused pending verification in the owner dashboard. Ownership, identity and account epoch changes revoke schedule keys; automatic backup jobs remain paused until current authority explicitly reenables them.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, cron, kind]
              properties:
                name: { type: string, minLength: 2, maxLength: 64 }
                cron: { type: string, examples: ['30 2 * * *'] }
                kind: { type: string, enum: [health, backup, webhook] }
                target: { type: string, format: uri, description: Required for a webhook }
      responses:
        '201': { description: Schedule created }
        '400': { description: Invalid schedule details }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '404': { description: Project or current owner authorization unavailable }
        '409': { description: Schedule capacity reached or backup job already exists }
        '503': { description: Schedules disabled or current authorization/policy/metadata unavailable }
  /api/projects/{projectId}/schedules/{jobId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ScheduleJobId'
    patch:
      operationId: updateSchedule
      description: Update the captured current job under a valid owner session or scoped schedule key. Automatic backup scheduling can be reenabled by the current owner or a newly valid delegated schedule key; stale original authority and job revisions are rejected.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              properties:
                name: { type: string, minLength: 2, maxLength: 64 }
                cron: { type: string, examples: ['30 2 * * *'] }
                enabled: { type: boolean }
      responses:
        '200': { description: Schedule updated }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '404': { description: Schedule not found }
        '409': { description: Schedule changed or requires webhook verification }
        '503': { description: Schedules disabled or current authorization/policy/metadata unavailable }
    delete:
      operationId: deleteSchedule
      description: Remove this captured schedule, its run history and saved backups under current owner/session or exact scoped-key proof. This explicit deletion differs from access revocation, which preserves snapshots and counters.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      responses:
        '200': { description: Schedule deleted }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '404': { description: Schedule not found }
        '503': { description: Current authorization, policy or metadata could not be verified }
  /api/projects/{projectId}/schedules/{jobId}/run:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ScheduleJobId'
    post:
      operationId: runSchedule
      description: Explicitly run an existing job with current owner-session or scoped-key authority. Manual backup runs remain allowed while automatic scheduling is paused. A backup export and final snapshot insert retain the original run owner/access epoch, job identity/revision and Records generation; changed authority/source cannot publish the snapshot. Run admission remains charged after later failure and grants no rollback, recovery or billing authority.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      responses:
        '200': { description: Run result, including success or failure status }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '404': { description: Job, captured source or current owner authorization unavailable }
        '409': { description: Verify the webhook and configure the signing key }
        '429': { description: Another run is active or the daily allowance is exhausted }
        '503': { description: Schedules disabled or current authorization/policy/metadata unavailable }
  /api/projects/{projectId}/schedules/{jobId}/runs:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ScheduleJobId'
    get:
      operationId: listScheduleRuns
      description: Read retained runs only while captured current owner/session or the exact scoped schedule key and job identity remain valid.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      responses:
        '200': { description: Up to 20 recent runs }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '404': { description: Schedule not found }
        '503': { description: Current authorization, policy or metadata could not be verified }
  /api/projects/{projectId}/schedules/{jobId}/backup:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ScheduleJobId'
    get:
      operationId: downloadScheduledBackup
      description: Download the latest retained snapshot with a current owner session or exact scoped schedule key. Any explicit snapshot selection requires the owner session, including selection of the latest snapshot by ID. Original owner/access epoch, exact session/key expiry and revocation, project/job identity and current policy are checked in SQL and before return. Revocation preserves retained backups while withholding data from stale credentials.
      security: [{ ScheduleToken: [] }, { OwnerSession: [] }]
      parameters:
        - in: query
          name: snapshot
          description: Owner-session-only selection. Scoped keys must omit this parameter; duplicates and invalid IDs are rejected.
          schema: { type: string, pattern: '^[1-9][0-9]{0,15}$' }
      responses:
        '200':
          description: Selected or latest Records export, including an empty snapshot
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RecordsExport' }
        '400': { description: Invalid or duplicate snapshot selection }
        '401': { description: Scoped schedule key expired, revoked or changed }
        '403': { description: Explicit snapshot selection requires the owner session }
        '404': { description: No backup is available }
        '503': { description: Current authorization, policy or metadata could not be verified }
  /api/projects/{projectId}/schedules/{jobId}/backups:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ScheduleJobId'
    get:
      operationId: listScheduledBackups
      description: List up to three retained snapshots with their IDs, creation times and byte sizes under the current owner session only. Scoped schedule keys cannot list backup history. Captured owner/access epoch, exact session and job identity are checked before return.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { description: Backup metadata and retention limits }
        '401': { description: Current owner session required or invalid scoped credential supplied }
        '403': { description: Scoped schedule keys cannot use backup history }
        '404': { description: Backup schedule unavailable }
        '503': { description: Current authorization, policy or metadata could not be verified }
  /api/sql/{projectId}/query:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: queryDedicatedSql
      description: Run one SQLite statement against a provisioned dedicated project database. JSON is limited to 32768 bytes, depth 8 and 4096 structural tokens, with a five-second body-read deadline. Current captured owner authorization, account policy, billing enrollment, token expiry and the database binding are rechecked before provider dispatch and before returning private results. Ownership, identity and account changes revoke the SQL token; restoring earlier state does not reactivate it. An admitted query remains reserved on failure. Unknown provider usage blocks new statements across UTC day changes until explicit operator reconciliation. An error after dispatch does not establish that a remote mutation was rolled back.
      security: [{ SqlToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sql]
              properties:
                sql: { type: string, maxLength: 16384 }
                params:
                  type: array
                  maxItems: 100
                  items: { type: string, maxLength: 2048 }
      responses:
        '200': { description: Query rows and reported usage }
        '400': { description: Invalid query, JSON, UTF-8, body length or structure }
        '401': { description: Invalid, expired or revoked SQL token, or captured project authorization or service policy no longer current }
        '408': { description: Request body aborted or its five-second read deadline exceeded }
        '409': { description: Database unavailable or another operation is running }
        '413': { description: Request body exceeds 32768 bytes }
        '429': { description: Daily SQL allowance reached or provider usage requires reconciliation; uncertainty does not clear at UTC rollover }
        '502': { description: Provider response invalid or remote outcome unconfirmed; no rollback or finality is established }
        '503': { description: Database service or provider unavailable; a dispatched operation may still require reconciliation }
  /api/data/{projectId}/{collection}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Collection'
    get:
      operationId: listDatabaseRecords
      description: List up to 25 Records under the captured current owner session or exact Records key. Ownership/account/identity/access-epoch, store generation, session or token expiry and live policy are checked at admission/read/final return. One monthly runtime attempt is reserved before processing and is not refunded after later failure. Corrupt/future counters fail closed. Successful output contains no private authorization proof.
      security: [{ DatabaseToken: [] }, { OwnerSession: [] }]
      parameters:
        - in: query
          name: after
          schema: { type: string, maxLength: 64 }
      responses:
        '200':
          description: Up to 25 Records with optional next key cursor
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RecordsRecordPage' }
        '400': { description: Invalid pagination cursor }
        '401': { description: Records key invalid, expired, revoked or no longer bound to captured authority/store }
        '404': { description: Project/store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Owner request's captured store lifecycle changed }
        '429': { description: Project data operation allowance reached }
        '503': { description: Current policy, safe record data or valid nonfuture usage could not be verified }
  /api/data/{projectId}/{collection}/{key}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/Collection'
      - in: path
        name: key
        required: true
        schema: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
    get:
      operationId: readDatabaseRecord
      description: Read one record with its unchanged quoted revision ETag. Captured original owner/epoch/store and exact session or key are checked in SQL and before disclosure. An admitted attempt remains charged on later failure.
      security: [{ DatabaseToken: [] }, { OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/RecordsRecord' }
        '401': { description: Records key invalid, expired, revoked or no longer bound to captured authority/store }
        '404': { description: Record, store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Owner request's captured store lifecycle changed }
        '429': { description: Monthly runtime attempt allowance reached }
        '503': { description: Current policy, safe record data or valid nonfuture usage could not be verified }
    put:
      operationId: saveDatabaseRecord
      description: Save one JSON value of at most 4096 serialized bytes. The value-only JSON envelope allows 4196 bytes, depth 20 and 4196 structural tokens with a five-second body deadline. One monthly attempt is reserved before body parsing and remains charged after invalid input, conditional failure or later access loss. SQL writes and final disclosure recheck original authority/store and exact session/key. If-None-Match * creates only; quoted If-Match preserves revision compare-and-swap.
      security: [{ DatabaseToken: [] }, { OwnerSession: [] }]
      parameters:
        - in: header
          name: If-Match
          schema: { type: string }
        - in: header
          name: If-None-Match
          schema: { type: string, enum: ['*'] }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [value]
              properties:
                value: {}
      responses:
        '200': { $ref: '#/components/responses/RecordsRecord' }
        '400': { description: Invalid value-only JSON, UTF-8, structure, declared length or conditional header }
        '401': { description: Records key invalid, expired, revoked or no longer bound to captured authority/store }
        '403': { description: Invalid browser origin for an owner-session mutation }
        '404': { description: Store or current owner authorization unavailable }
        '408': { description: Request aborted or five-second body-read deadline exceeded }
        '409': { description: Capacity or credentials changed }
        '412': { description: Conditional write failed }
        '413': { description: Envelope exceeds 4196 bytes or serialized value exceeds 4096 bytes }
        '429': { description: Monthly runtime attempt allowance reached }
        '503': { description: Current policy, safe record data or valid nonfuture usage could not be verified }
    delete:
      operationId: deleteDatabaseRecord
      description: Delete one record under current captured owner/epoch/store and exact session or key. Quoted If-Match still requires its current revision. An admitted monthly attempt is not refunded after a failed condition or later access loss.
      security: [{ DatabaseToken: [] }, { OwnerSession: [] }]
      parameters:
        - in: header
          name: If-Match
          schema: { type: string }
      responses:
        '200': { description: Record deleted }
        '400': { description: Invalid conditional header }
        '401': { description: Records key invalid, expired, revoked or no longer bound to captured authority/store }
        '403': { description: Invalid browser origin for an owner-session mutation }
        '404': { description: Record, store or current owner authorization unavailable }
        '408': { description: Request aborted }
        '409': { description: Owner request's captured store lifecycle changed }
        '412': { description: Conditional delete failed }
        '429': { description: Monthly runtime attempt allowance reached }
        '503': { description: Current policy or valid nonfuture usage could not be verified }
  /api/projects/{projectId}/ci-deploy:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: deployStarter
      description: Publish or stage a managed starter. ZIP uploads contain a single root launch.json.
      parameters:
        - in: query
          name: stage
          description: Set to 1 to stage a ZIP release.
          schema: { type: string, enum: ['1'] }
        - in: query
          name: tag
          description: Set the tag on a ZIP release.
          schema: { type: string }
        - in: query
          name: commit
          description: Set the Git commit SHA on a ZIP release.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, message]
              properties:
                title: { type: string, maxLength: 80 }
                message: { type: string, maxLength: 500 }
                template: { type: string, enum: [landing-page-v1, status-api-v1, business-site-v1] }
                site:
                  type: object
                  required: [theme, sections]
                  properties:
                    theme: { type: string, enum: [moss, ocean, clay] }
                    contactEmail: { type: string, maxLength: 128 }
                    leadCapture: { type: boolean }
                    sections:
                      type: array
                      minItems: 1
                      maxItems: 3
                      items:
                        type: object
                        required: [heading, text]
                        properties:
                          heading: { type: string, maxLength: 65 }
                          text: { type: string, maxLength: 350 }
              if:
                required: [template]
                properties:
                  template: { const: business-site-v1 }
              then:
                required: [site]
                tag: { type: string, maxLength: 40 }
                stage: { type: boolean }
                commit: { type: string, pattern: '^[a-f0-9]{40}$' }
          application/zip:
            schema: { type: string, format: binary }
      responses:
        '201': { description: Starter release saved }
        '400': { description: Invalid starter }
        '401': { description: Invalid or expired project token }
        '409': { description: Release conflict or project limit reached }
  /api/projects/{projectId}/ci-preview-token:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getCiPreviewTokenStatus
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Expiration of the active preview token
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CiPreviewTokenStatus' }
        '404': { description: Project unavailable }
    post:
      operationId: rotateCiPreviewToken
      description: Issue a 30-day preview token and invalidate the previous one. Store the token from this response.
      security: [{ OwnerSession: [] }]
      responses:
        '201':
          description: Preview token issued
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CiPreviewTokenStatus'
                  - type: object
                    required: [token]
                    properties:
                      token: { type: string, pattern: '^spv_[a-f0-9]{64}$' }
        '404': { description: Project unavailable }
    delete:
      operationId: revokeCiPreviewToken
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Preview token revoked
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CiPreviewTokenStatus' }
        '404': { description: Project unavailable }
  /api/projects/{projectId}/ci-deploy/static:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: stageStaticSite
      description: Stage a prebuilt ZIP with index.html at the root.
      security: [{ DeployToken: [] }, { CiPreviewToken: [] }]
      parameters:
        - in: query
          name: spa
          schema: { type: string, enum: ['0', '1'] }
        - in: query
          name: assetAffinity
          description: Add the release ID to supported HTML asset links marked data-stackr-release.
          schema: { type: string, enum: ['0', '1'] }
        - in: query
          name: tag
          schema: { type: string, maxLength: 40 }
        - in: query
          name: commit
          schema: { type: string, pattern: '^[a-f0-9]{40}$' }
      requestBody:
        required: true
        content:
          application/zip:
            schema: { type: string, format: binary }
      responses:
        '201': { description: Site archive staged }
        '400': { description: Invalid archive }
        '401': { description: Invalid or expired project token }
        '409': { description: Release conflict or project limit reached }
        '503': { description: Site hosting is unavailable }
  /api/projects/{projectId}/ci-deploy/preview:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: previewRelease
      description: Preview a release with a deploy token. Static previews return an expiring URL.
      parameters:
        - in: query
          name: release
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Managed preview }
        '302': { description: Expiring isolated site preview }
        '401': { description: Invalid or expired deploy token }
        '404': { description: Release not found }
  /api/projects/{projectId}/ci-deploy/check:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: checkRelease
      description: Read the template and active state of one release.
      parameters:
        - in: query
          name: release
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200': { description: Release metadata }
        '401': { description: Invalid or expired deploy token }
        '404': { description: Release not found }
  /api/projects/{projectId}/ci-deploy/usage:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getUsage
      responses:
        '200': { description: Monthly requests and response telemetry }
        '401': { description: Invalid or expired project token }
  /api/projects/{projectId}/ci-deploy/deployments:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listReleases
      responses:
        '200': { description: Recent releases with active release first }
        '401': { description: Invalid or expired project token }
  /api/projects/{projectId}/ci-deploy/copy:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: copyStaticRelease
      description: Stage a private static release copy using a full project deploy token.
      security: [{ DeployToken: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/StaticReleaseCopyOptions'
                - type: object
                  required: [releaseId]
                  properties:
                    releaseId: { type: string, format: uuid }
      responses:
        '200': { $ref: '#/components/responses/StaticReleaseCopyReceipt' }
        '201': { $ref: '#/components/responses/StaticReleaseCopyReceipt' }
        '400': { description: Invalid source release ID, tag, or operation ID }
        '401': { description: Invalid or expired project deploy token }
        '404': { description: Source release unavailable }
        '409': { description: Release cannot be copied, tag or operation conflicts, or project capacity reached }
  /api/projects/{projectId}/ci-deploy/promote:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: promoteRelease
      description: Activate a release, including a previous release for rollback.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [deploymentId]
              properties:
                deploymentId: { type: string, format: uuid }
      responses:
        '200': { description: Release activated }
        '401': { description: Invalid or expired project token }
        '409': { description: Release conflict }
  /api/usage-billing/operator/cost-evidence:
    post:
      operationId: registerUsageCostAllocationEvidence
      description: Record a bounded immutable provider invoice document and its exact allocation to an enrolled workspace. Requires the separate configured usage-billing operator bearer on the canonical Stackr HTTPS origin and rejects Cookie and Origin headers. No provider is queried, invoice issued, payment executed, source artifact fetched or source authenticity established. The closed UTC month, complete allocation sum, unique workspace IDs, active billing consent, commission and invoice cap are rechecked. Body is limited to 65536 bytes, depth 8 and 4000 structural tokens with a five-second read deadline.
      security: [{ UsageBillingOperator: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UsageCostEvidenceDocument' }
      responses:
        '201':
          description: Immutable allocation stored or identical evidence deduplicated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UsageCostAllocationResponse' }
        '400': { description: Incomplete, estimated, duplicate-workspace, non-USD, non-closed-period or inconsistent allocation evidence }
        '401': { description: Separate usage-billing operator bearer required; Cookie and Origin are rejected }
        '404': { description: No eligible billing owner/enrollment }
        '408': { description: Body aborted or read deadline exceeded }
        '409': { description: Evidence, consent, customer or configured tariff changed or conflicts with immutable lineage }
        '413': { description: Body exceeds the byte limit }
        '415': { description: Send the evidence as application/json }
        '429': { description: Bounded evidence capacity exhausted }
        '503': { description: Usage billing gates or evidence schema unavailable }
  /api/projects/{projectId}/infrastructure/billing:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getOwnerManagedUsageBilling
      description: Read the current project owner's billing enrollment, up to 24 periods and up to 24 recent live-mode cost allocations. The same typed billing view is included in the aggregate project infrastructure response. Current project, session, account, identity and configuration policy are checked after asynchronous reads. Stored evidence is advisory about source authenticity; no provider is queried or payment authorized by this read.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Current owner billing view with bounded typed cost evidence where available
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ManagedUsageBilling' }
        '401': { description: Owner sign-in required }
        '403': { description: Current owner context unavailable }
        '404': { description: Current project or owner access unavailable }
        '503': { description: Billing state could not be verified }
    post:
      operationId: reviewOwnerUsageCostAllocation
      description: Record or revoke a separate owner review of the exact displayed allocation digest and review revision. Requires the current owner session, exact canonical Origin and application/json, with no Authorization header or query parameters. Body is limited to 2048 bytes, depth 4 and 64 structural tokens with a five-second deadline. The server rechecks current project/session/account policy, billing enrollment, customer, consent revision and commission/invoice cap before update and return. Confirming does not authenticate the source or execute a payment. Revocation does not reverse an issued invoice.
      security: [{ OwnerSession: [] }]
      parameters:
        - name: Origin
          in: header
          required: true
          schema: { type: string, format: uri }
          description: Exact canonical Stackr HTTPS origin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UsageCostAllocationReview' }
      responses:
        '200':
          description: Owner review recorded or revoked; an identical repeat preserves its revision
          content:
            application/json:
              schema: { $ref: '#/components/schemas/UsageCostAllocationResponse' }
        '400': { description: Invalid bounded review or unexpected query parameters }
        '401': { description: Owner session required; bearer substitution rejected }
        '403': { description: Missing/incorrect Origin or lost current project/account authorization }
        '404': { description: Allocation or current owner/project access unavailable }
        '408': { description: Request aborted or body deadline exceeded }
        '409': { description: Digest, revision, enrollment, customer, tariff or current context changed; refresh and review again }
        '413': { description: Body exceeds the byte limit }
        '415': { description: Send the review as application/json }
        '429': { description: Review revision capacity exhausted; final revocation is reserved }
        '503': { description: Billing or evidence controls unavailable }
  /api/runtime-spending:
    get:
      operationId: getOwnerRuntimeSpending
      description: Read the current owner's runtime tariff, consent revision, service and aggregate spending caps, and cumulative nonrefundable reservations in the SQL UTC month. Requires an owner session on the canonical HTTPS origin; bearer credentials grant no authority. Reading or saving consent does not activate paid hosting.
      security: [{ OwnerSession: [] }]
      responses:
        '200':
          description: Current runtime tariff, owner policy and UTC reservations
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RuntimeSpending' }
        '401': { description: Owner session required; bearer authority is rejected }
        '403': { description: Origin is not the canonical Stackr origin }
        '404': { description: Current owner identity, session or account access is unavailable }
        '503': { description: Runtime spending state could not be verified }
    put:
      operationId: saveOwnerRuntimeSpending
      description: Explicitly accept the currently displayed tariff digest and set nonrefundable monthly runtime caps. Includes the current policy revision, or zero for a first policy. Caps use millionths of USD, each service cap must fit within the aggregate cap, and a zero service cap blocks that service. At least one offered service cap must cover one bounded execution. Preview and live executions share the caps. A tariff or revision change requires fresh review. No feature is activated, no payment is initiated, and existing reservations are never refunded.
      security: [{ OwnerSession: [] }]
      parameters:
        - name: Origin
          in: header
          required: true
          schema: { type: string, format: uri }
          description: Exact canonical Stackr HTTPS origin
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RuntimeSpendingSettings' }
      responses:
        '200':
          description: Reviewed runtime consent saved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RuntimeSpending' }
        '400': { description: Invalid current revision, tariff digest, bounded JSON or spending caps }
        '401': { description: Owner session required; bearer authority is rejected }
        '403': { description: Missing or invalid canonical Origin }
        '404': { description: Current owner identity, session or account access is unavailable }
        '409': { description: Tariff, policy revision or owner access changed; refresh and review again }
        '415': { description: Send the reviewed policy as application/json without query parameters }
        '503': { description: Runtime tariff or live funding is unavailable }
    delete:
      operationId: revokeOwnerRuntimeSpending
      description: Revoke future runtime spending consent using the current policy revision. Retains a monotonic disabled policy and all nonrefundable UTC monthly reservations. This does not refund funds or terminate a request already admitted.
      security: [{ OwnerSession: [] }]
      parameters:
        - name: revision
          in: query
          required: true
          schema: { type: integer, minimum: 1, maximum: 9007199254740990 }
        - name: Origin
          in: header
          required: true
          schema: { type: string, format: uri }
          description: Exact canonical Stackr HTTPS origin
      responses:
        '200':
          description: Consent revoked; previous reservations retained
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RuntimeSpending' }
        '400': { description: Supply only the current policy revision query parameter }
        '401': { description: Owner session required; bearer authority is rejected }
        '403': { description: Missing or invalid canonical Origin }
        '404': { description: Current owner identity, session or account access is unavailable }
        '409': { description: The policy or current owner access changed }
        '503': { description: Runtime spending state could not be verified }
  /api/usage/traffic-cap:
    get:
      operationId: getWorkspaceHostedRequestCap
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/WorkspaceHostedRequestCap' }
        '401': { description: Stackr sign-in required }
    put:
      operationId: saveWorkspaceHostedRequestCap
      description: Set or clear the monthly hosted request cap using the current revision. The request count remains cumulative within the UTC month.
      security: [{ OwnerSession: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WorkspaceHostedRequestCapSettings' }
      responses:
        '200': { $ref: '#/components/responses/WorkspaceHostedRequestCap' }
        '400': { description: Invalid request limit or revision }
        '401': { description: Stackr sign-in required }
        '403': { description: Request origin rejected }
        '409': { description: Cap changed since the submitted revision }
  /api/usage-wallet/overage:
    get:
      operationId: readTrafficOverage
      description: Read the signed-in owner's traffic overage consent, current price, and paid usage in the current UTC month.
      security: [{ OwnerSession: [] }]
      responses:
        '200': { $ref: '#/components/responses/TrafficOverageSettings' }
        '401': { description: Stackr owner sign-in required }
        '503': { description: Usage settings are unavailable }
    put:
      operationId: saveTrafficOverage
      description: Authorize prepaid charges for eligible requests beyond the workspace free allowance, at the current rate and within a monthly spending cap. The platform daily request limit still applies.
      security: [{ OwnerSession: [] }]
      parameters:
        - $ref: '#/components/parameters/TrafficOverageOrigin'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [acceptedPriceMicros, maxMonthlyMicros]
              properties:
                acceptedPriceMicros: { type: integer, minimum: 1, maximum: 100000, description: Current price per eligible request in millionths of a US dollar }
                maxMonthlyMicros: { type: integer, minimum: 1, maximum: 100000000, description: Monthly spending cap in millionths of a US dollar. Must cover at least one eligible request. }
      responses:
        '200': { $ref: '#/components/responses/TrafficOverageSettings' }
        '400': { description: Invalid price or monthly spending cap }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin does not match the Stackr request origin }
        '409': { description: Price changed and requires review }
        '503': { description: Traffic overage is unavailable }
    delete:
      operationId: disableTrafficOverage
      description: Revoke consent for future traffic overage charges. Previous paid usage is retained.
      security: [{ OwnerSession: [] }]
      parameters:
        - $ref: '#/components/parameters/TrafficOverageOrigin'
      responses:
        '200': { $ref: '#/components/responses/TrafficOverageSettings' }
        '401': { description: Stackr owner sign-in required }
        '403': { description: Origin does not match the Stackr request origin }
        '503': { description: Usage settings are unavailable }
components:
  schemas:
    UsageCostEvidenceDocument:
      type: object
      additionalProperties: false
      required: [ownerId, period, provider, sourceReference, sourceDigest, currency, evidenceKind, invoiceTotalMicros, allocations, completeness]
      properties:
        ownerId: { type: string, format: uuid, description: Selected enrolled workspace; must occur exactly once in allocations }
        period: { type: string, pattern: '^20[0-9]{2}-(0[1-9]|1[0-2])$', description: Closed UTC month before the current server month }
        provider: { $ref: '#/components/schemas/UsageCostReference' }
        sourceReference: { $ref: '#/components/schemas/UsageCostReference' }
        sourceDigest: { type: string, pattern: '^[a-f0-9]{64}$', description: SHA-256 of externally retained source evidence; does not authenticate that source }
        currency: { type: string, const: USD }
        evidenceKind: { type: string, const: invoice }
        invoiceTotalMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        allocations:
          type: array
          minItems: 1
          maxItems: 100
          uniqueItems: true
          description: Workspace IDs must be unique and providerMicros must sum exactly to invoiceTotalMicros
          items:
            type: object
            additionalProperties: false
            required: [workspaceId, providerMicros]
            properties:
              workspaceId: { type: string, format: uuid }
              providerMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        completeness:
          type: object
          additionalProperties: false
          required: [unallocatedMicros, unexplainedMicros, estimatedAttributionMicros, measurementsComplete]
          properties:
            unallocatedMicros: { type: integer, const: 0 }
            unexplainedMicros: { type: integer, const: 0 }
            estimatedAttributionMicros: { type: integer, const: 0 }
            measurementsComplete: { type: boolean, const: true }
    UsageCostReference:
      type: string
      maxLength: 160
      pattern: '^[A-Za-z0-9][A-Za-z0-9:._/-]{0,159}$'
    UsageCostAllocationReview:
      type: object
      additionalProperties: false
      required: [allocationId, allocationDigest, expectedRevision, confirmed]
      properties:
        allocationId: { type: string, format: uuid }
        allocationDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        expectedRevision: { type: integer, minimum: 0, maximum: 16 }
        confirmed: { type: boolean, description: True records the explicit owner review; false revokes it }
    UsageCostAllocationResponse:
      type: object
      additionalProperties: false
      required: [allocation]
      properties:
        allocation: { $ref: '#/components/schemas/UsageCostAllocation' }
    UsageCostAllocation:
      type: object
      additionalProperties: false
      required: [allocationId, allocationDigest, documentDigest, provider, period, sourceReference, sourceDigest, providerMicros, currency, commissionBps, maxInvoiceCents, commissionMicros, totalCents, consentReference, consentRevision, reviewRevision, ownerReviewedAt, ownerRevokedAt, current, ownerReviewCurrent, sourceAuthenticityVerified, paymentExecutionAuthorized]
      properties:
        allocationId: { type: string, format: uuid }
        allocationDigest: { type: string, pattern: '^[a-f0-9]{64}$', description: Immutable digest binds the complete source document, selected allocation, billing consent and tariff }
        documentDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        provider: { $ref: '#/components/schemas/UsageCostReference' }
        period: { type: string, pattern: '^20[0-9]{2}-(0[1-9]|1[0-2])$' }
        sourceReference: { $ref: '#/components/schemas/UsageCostReference' }
        sourceDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        providerMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        currency: { type: string, const: USD }
        commissionBps: { type: integer, minimum: 0, maximum: 10000 }
        maxInvoiceCents: { type: integer, minimum: 50, maximum: 99999999 }
        commissionMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        totalCents: { type: integer, minimum: 0, maximum: 200000000 }
        consentReference: { $ref: '#/components/schemas/UsageCostReference' }
        consentRevision: { type: integer, minimum: 1, maximum: 9007199254740991 }
        reviewRevision: { type: integer, minimum: 0, maximum: 16 }
        ownerReviewedAt: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
        ownerRevokedAt: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
        current: { type: boolean, description: Captured billing enrollment/customer/consent and tariff still match }
        ownerReviewCurrent: { type: boolean, description: Current original-owner identity has a matching unrevoked review }
        sourceAuthenticityVerified: { type: boolean, const: false }
        paymentExecutionAuthorized: { type: boolean, const: false }
    UsageCostEvidenceListing:
      type: object
      additionalProperties: false
      required: [available, allocations]
      properties:
        available: { type: boolean }
        allocations:
          type: array
          maxItems: 24
          items: { $ref: '#/components/schemas/UsageCostAllocation' }
    ManagedUsageBillingPeriod:
      type: object
      additionalProperties: false
      required: [period, state, providerMicros, commissionMicros, commissionBps, totalCents, currency, hostedInvoiceUrl]
      properties:
        period: { type: string, pattern: '^20[0-9]{2}-(0[1-9]|1[0-2])$' }
        state: { type: string, enum: [reconciled, issued, paid, void, uncollectible, below_minimum, review] }
        providerMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        commissionMicros: { type: integer, minimum: 0, maximum: 1000000000000 }
        commissionBps: { type: integer, minimum: 0, maximum: 10000 }
        totalCents: { type: integer, minimum: 0, maximum: 200000000 }
        currency: { type: string, const: usd }
        hostedInvoiceUrl: { type: [string, 'null'], format: uri }
        costEvidence:
          type: object
          additionalProperties: false
          required: [allocationId, allocationDigest]
          properties:
            allocationId: { type: string, format: uuid }
            allocationDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
    ManagedUsageBilling:
      type: object
      additionalProperties: false
      required: [enabled, enrolled, periods]
      properties:
        enabled: { type: boolean }
        enrolled: { type: boolean }
        mode: { type: string, enum: [test, live] }
        reason: { type: [string, 'null'] }
        periods:
          type: array
          maxItems: 24
          items: { $ref: '#/components/schemas/ManagedUsageBillingPeriod' }
        costEvidence: { $ref: '#/components/schemas/UsageCostEvidenceListing' }
    RuntimeSpendingServices:
      type: object
      additionalProperties: false
      required: [javascript, container-lite, container-standard-1]
      properties:
        javascript: { type: integer, minimum: 0, maximum: 100000000 }
        container-lite: { type: integer, minimum: 0, maximum: 100000000 }
        container-standard-1: { type: integer, minimum: 0, maximum: 100000000 }
    RuntimeSpendingSettings:
      type: object
      additionalProperties: false
      required: [revision, acceptedTariffId, maxMonthlyMicros, serviceCapsMicros]
      properties:
        revision: { type: integer, minimum: 0, maximum: 9007199254740990 }
        acceptedTariffId: { type: string, pattern: '^[a-f0-9]{64}$' }
        maxMonthlyMicros: { type: integer, minimum: 1, maximum: 100000000 }
        serviceCapsMicros: { $ref: '#/components/schemas/RuntimeSpendingServices' }
    RuntimeSpending:
      type: object
      additionalProperties: false
      required: [available, currency, month, tariff, policy, usage, maxAllowedMonthlyMicros, requiresReview]
      properties:
        available: { type: boolean, description: A current tariff and live funding configuration are available; this does not establish runtime feature availability }
        currency: { type: string, const: USD }
        month: { type: string, pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$' }
        tariff:
          oneOf:
            - { type: 'null' }
            - type: object
              additionalProperties: false
              required: [id, revision, pricesMicros]
              properties:
                id: { type: string, pattern: '^[a-f0-9]{64}$', description: Digest binds the exact revision and all three configured prices }
                revision: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$' }
                pricesMicros:
                  type: object
                  additionalProperties: false
                  required: [javascript, container-lite, container-standard-1]
                  properties:
                    javascript: { type: [integer, 'null'], minimum: 1, maximum: 999999, description: USD millionths per eligible bounded execution }
                    container-lite: { type: [integer, 'null'], minimum: 1, maximum: 1000000, description: USD millionths per eligible bounded execution, not per second }
                    container-standard-1: { type: [integer, 'null'], minimum: 1, maximum: 1000000, description: USD millionths per eligible bounded execution, not per second }
        policy:
          oneOf:
            - { type: 'null' }
            - type: object
              additionalProperties: false
              required: [revision, enabled, acceptedTariffId, acceptedTariffRevision, maxMonthlyMicros, serviceCapsMicros, consentedAt]
              properties:
                revision: { type: integer, minimum: 1, maximum: 9007199254740991 }
                enabled: { type: boolean }
                acceptedTariffId: { type: string, pattern: '^[a-f0-9]{64}$' }
                acceptedTariffRevision: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$' }
                maxMonthlyMicros: { type: integer, minimum: 1, maximum: 100000000 }
                serviceCapsMicros: { $ref: '#/components/schemas/RuntimeSpendingServices' }
                consentedAt: { type: integer, minimum: 0, maximum: 9007199254740991 }
        usage:
          type: object
          additionalProperties: false
          required: [totalMicros, servicesMicros, reconciliationRequired]
          properties:
            totalMicros: { type: integer, minimum: 0, maximum: 100000000, description: Nonrefundable aggregate reservations in the current SQL UTC month }
            servicesMicros: { $ref: '#/components/schemas/RuntimeSpendingServices' }
            reconciliationRequired: { type: boolean, description: An unconfirmed reservation blocks further runtime admission. Recorded totals may be incomplete; changing consent does not release the hold. }
        maxAllowedMonthlyMicros: { type: integer, const: 100000000 }
        requiresReview: { type: boolean }
    NativeServiceOperationReservation:
      type: object
      additionalProperties: false
      required: [status, periodKind, period, admittedAt, scope, queriesReserved, readsReserved, writesReserved]
      properties:
        status: { type: string, enum: [recorded, unrecorded, not_applicable] }
        periodKind: { type: [string, 'null'], enum: [utc-day, null] }
        period: { type: [string, 'null'], format: date, pattern: '^\d{4}-\d{2}-\d{2}$' }
        admittedAt: { type: [integer, 'null'], minimum: 0, maximum: 8640000000000000, multipleOf: 1000 }
        scope: { type: [string, 'null'], enum: [project, account-shared, null] }
        queriesReserved: { type: [integer, 'null'], minimum: 0, maximum: 1000 }
        readsReserved: { type: [integer, 'null'], minimum: 0, maximum: 1 }
        writesReserved: { type: [integer, 'null'], minimum: 0, maximum: 1 }
      oneOf:
        - properties:
            status: { enum: [unrecorded, not_applicable] }
            periodKind: { type: 'null' }
            period: { type: 'null' }
            admittedAt: { type: 'null' }
            scope: { type: 'null' }
            queriesReserved: { type: 'null' }
            readsReserved: { type: 'null' }
            writesReserved: { type: 'null' }
        - properties:
            status: { const: recorded }
            periodKind: { const: utc-day }
            period: { type: string }
            admittedAt: { type: integer }
            scope: { const: project }
            queriesReserved: { type: integer, minimum: 1, maximum: 1000 }
            readsReserved: { const: 0 }
            writesReserved: { const: 0 }
        - properties:
            status: { const: recorded }
            periodKind: { const: utc-day }
            period: { type: string }
            admittedAt: { type: integer }
            scope: { const: account-shared }
            queriesReserved: { const: 0 }
            readsReserved: { const: 0 }
            writesReserved: { const: 1 }
      description: Redacted operation-only quota admission evidence. Recorded means the guarded debit transition and resulting counter/revision checks confirmed this receipt; a persisted candidate or SQLite RETURNING row alone is insufficient. Accepted confirmation and verified charge are atomic under the guarded protocol. New SQL query/migration receipts charge project query units; new KV key PUT/DELETE receipts charge one account-shared write unit. Confirmation is read after a nonthrowing INSERT only; a database exception is never converted into readback success. Every covered RPC requires confirmed admission. The recorded original UTC period/time remains proof of that admission without requiring latest shared-counter/current-day equality. Exact same-confirmed-operation replay does not charge twice; ambiguous acknowledgements cause no automatic admission retry or unproven provider dispatch. Unrecorded includes legacy, denied-admission or unconfirmed candidates. An unconfirmed candidate has null charged fields or unavailable unsafe metadata, blocks provider dispatch and parent pruning, and proves neither accepted debit nor zero/no charge or refund authority. Not_applicable covers resource CRUD/replication outside this quota path. KV reads/listings retain existing shared read counters without new journal rows or receipts. Private raw-prior/before/after counters, limits, shared totals and source/credential identifiers are excluded. These quota units are not provider RPCs, SQL rows, money, refunds or correction/finality/execution authority.
    NativeServiceOperationSource:
      type: object
      additionalProperties: false
      required: [incarnationCurrent, leaseCurrent, authorityCurrent]
      properties:
        incarnationCurrent: { type: boolean, description: A stored source has the original incarnation, account and any provider ID recorded at start. A cold or replaced source is false; this is not a live provider check. }
        leaseCurrent: { type: boolean, description: That matching stored source carries the original lease ID. Expiry is not checked, so an expired lease can still be current here. }
        authorityCurrent: { type: boolean, description: Stored project owner, identity and access epoch match the original record, with the original trusted-or-unsuspended-account gate. This excludes live session, invite and configuration policy; it grants no authorization. }
    NativeServiceOperationRpc:
      type: object
      additionalProperties: false
      required: [dispatchPossible, mutationPossible, acknowledged, readObserved, rejected, unobserved, completeMeasurements, unknownMeasurements, rowsReadObserved, rowsWrittenObserved]
      properties:
        dispatchPossible: { type: integer, minimum: 0, maximum: 32, description: Possibility records persisted before fetch; a denied second guard or crash can leave a record without actual dispatch. }
        mutationPossible: { type: integer, minimum: 0, maximum: 32, description: Conservative mutation-class RPC possibilities. SQL query POSTs count as possible mutations. }
        acknowledged: { type: integer, minimum: 0, maximum: 32, description: Endpoint-validated acknowledgements of those mutation RPCs, including observations that arrive after original access/source changes; not provider finality. }
        readObserved: { type: integer, minimum: 0, maximum: 32, description: Observed read responses; discovery, readback or absence never acknowledges an earlier mutation. }
        rejected: { type: integer, minimum: 0, maximum: 32, description: Recorded RPC rejections. HTTP status alone establishes neither acknowledgement nor provider finality. }
        unobserved: { type: integer, minimum: 0, maximum: 32, description: Possible RPCs with no retained response observation. }
        completeMeasurements: { type: integer, minimum: 0, maximum: 32 }
        unknownMeasurements: { type: integer, minimum: 0, maximum: 32 }
        rowsReadObserved: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
        rowsWrittenObserved: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
      description: Response classes sum to dispatchPossible; complete and unknown measurements also sum to dispatchPossible. Row sums are only a safe observed subset and can be non-null while other measurements remain unknown. Null is not verified zero. Per-RPC measurements alone do not establish quota admission provenance; the separate reservation summary can establish a new covered local admission. Legacy records and KV reads/listings still lack receipt coverage, complete reservation history/invoices cannot be reconstructed, and usage correction remains unauthorized. These counts exclude journal/inspection overhead and are not verified provider usage or invoice totals.
    NativeServiceOperationRecord:
      type: object
      additionalProperties: false
      required: [operationId, service, kind, createdAt, finishedAt, outcome, coverageComplete, source, rpc, reservation]
      properties:
        operationId: { type: string, format: uuid, pattern: '^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$', description: Public journal-record identifier only; not a lease, provider, RPC, owner or credential identity. }
        service: { type: string, enum: [sql, kv] }
        kind: { type: string, enum: [sql_create, sql_delete, sql_replication, sql_query, sql_migration, kv_create, kv_delete, kv_put, kv_delete_key] }
        createdAt: { type: integer, minimum: 0, maximum: 8640000000000000, multipleOf: 1000, description: SQL-clock journal intent time. A recorded reservation separately exposes its covered quota admission period and admittedAt time. }
        finishedAt: { type: [integer, 'null'], minimum: 0, maximum: 8640000000000000, multipleOf: 1000 }
        outcome: { type: [string, 'null'], enum: [returned, failed, unverified, null], description: Recorded workflow outcome, not provider commit, rollback or customer-facing success. Null means no terminal workflow observation. }
        coverageComplete: { type: boolean, description: Explicit recorded workflow coverage. Interpret alongside RPC response and measurement counts; this alone establishes neither complete history nor finality. }
        source: { $ref: '#/components/schemas/NativeServiceOperationSource' }
        rpc: { $ref: '#/components/schemas/NativeServiceOperationRpc' }
        reservation: { $ref: '#/components/schemas/NativeServiceOperationReservation' }
      allOf:
        - if: { properties: { service: { const: sql } } }
          then: { properties: { kind: { enum: [sql_create, sql_delete, sql_replication, sql_query, sql_migration] } } }
          else: { properties: { kind: { enum: [kv_create, kv_delete, kv_put, kv_delete_key] } } }
        - if: { properties: { outcome: { type: 'null' } } }
          then: { properties: { finishedAt: { type: 'null' }, coverageComplete: { const: false } } }
          else: { properties: { finishedAt: { type: integer } } }
        - if: { properties: { kind: { enum: [sql_query, sql_migration] } } }
          then:
            properties:
              reservation:
                properties:
                  status: { enum: [recorded, unrecorded] }
                  scope: { enum: [project, null] }
        - if: { properties: { kind: { enum: [kv_put, kv_delete_key] } } }
          then:
            properties:
              reservation:
                properties:
                  status: { enum: [recorded, unrecorded] }
                  scope: { enum: [account-shared, null] }
        - if: { properties: { kind: { enum: [sql_create, sql_delete, sql_replication, kv_create, kv_delete] } } }
          then:
            properties:
              reservation:
                properties:
                  status: { const: not_applicable }
      description: Redacted immutable original intent with separately retained RPC observations and a version-2 quota receipt summary. No raw SQL, key, value, token, private request/response digest, prior/before/after counter snapshots, applied limits, shared totals, provider/account/owner/lease identity or RPC ID is disclosed. Late acknowledgements do not rewrite original authority or grant recovery execution. A recorded debit is nonrefundable even if no provider RPC follows; a new customer request remains a new admission.
    NativeServiceOperationsReport:
      type: object
      additionalProperties: false
      required: [version, kind, projectId, observedAt, accessEpoch, metadataRevision, operations, cursor, reservationHistoryComplete, historyComplete, observationsIncomplete, providerFinalityVerified, actualProviderUsageVerified, holdReleaseAuthorized, usageCorrectionAuthorized, providerActionsAuthorized, billingAuthorized, executable]
      properties:
        version: { const: 2 }
        kind: { const: stackr-native-service-operations }
        projectId: { type: string, format: uuid, pattern: '^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$' }
        observedAt: { type: integer, minimum: 0, maximum: 8640000000000000, multipleOf: 1000 }
        accessEpoch: { type: integer, minimum: 1, maximum: 9007199254740991 }
        metadataRevision: { type: integer, minimum: 1, maximum: 9007199254740991 }
        operations:
          type: array
          maxItems: 20
          items: { $ref: '#/components/schemas/NativeServiceOperationRecord' }
        cursor:
          type: [string, 'null']
          maxLength: 54
          pattern: '^(0|[1-9][0-9]{0,15})_([a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12})$'
          description: Last returned createdAt and operationId when a bounded 21st row exists; null otherwise. Pass unchanged for older records.
        reservationHistoryComplete: { const: false }
        historyComplete: { const: false }
        observationsIncomplete: { const: true }
        providerFinalityVerified: { const: false }
        actualProviderUsageVerified: { const: false }
        holdReleaseAuthorized: { const: false }
        usageCorrectionAuthorized: { const: false }
        providerActionsAuthorized: { const: false }
        billingAuthorized: { const: false }
        executable: { const: false }
      description: Version-2 bounded retained history, ordered by createdAt/operationId descending, with atomic quota receipt summaries for new covered SQL/KV admissions only. Owners see only original owner/identity/current-epoch records; operators can audit all retained target records. Reading the page performs no provider or native-service action. Legacy admissions are never backfilled, denied intents can be unrecorded, and KV reads/listings have no new journal rows; reservationHistoryComplete stays false. This cannot reconstruct complete reservations, costs or invoices or authorize usage correction/refunds. Recovery V1 snapshots/reviews remain separate and consume neither journal nor reservation details.
    NativeRecoveryAuthority:
      type: object
      required: [historyComplete, sharedKvUsageAttributed, providerIdentityVerified, actualProviderUsageVerified, holdReleaseAuthorized, usageCorrectionAuthorized, providerActionsAuthorized, billingAuthorized, executable]
      properties:
        historyComplete: { const: false }
        sharedKvUsageAttributed: { const: false }
        providerIdentityVerified: { const: false }
        actualProviderUsageVerified: { const: false }
        holdReleaseAuthorized: { const: false }
        usageCorrectionAuthorized: { const: false }
        providerActionsAuthorized: { const: false }
        billingAuthorized: { const: false }
        executable: { const: false }
      description: Metadata and unsigned advisory comparison establish none of these facts or authorities. The V1 snapshot/review does not consume the separate operation journal and carries no original-operation or finality receipts.
    NativeRecoveryOperation:
      type: object
      additionalProperties: false
      required: [kind, dispatch, acknowledgement, finality]
      properties:
        kind: { const: unrecorded }
        dispatch: { const: unrecorded }
        acknowledgement: { const: unrecorded }
        finality: { const: unverified }
      description: V1 snapshot/review placeholder; this report does not consume the separate operation journal. Resource state and a hold cannot establish the original operation, dispatch, acknowledgement or provider finality, and legacy holds gain no retroactive receipts.
    NativeRecoveryLease:
      type: object
      additionalProperties: false
      required: [present, status, expiresAt]
      properties:
        present: { type: boolean }
        status: { type: string, enum: [none, temporary_active, temporary_expired, durable_hold] }
        expiresAt: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
      oneOf:
        - properties:
            present: { const: false }
            status: { const: none }
            expiresAt: { type: 'null' }
        - properties:
            present: { const: true }
            status: { const: durable_hold }
            expiresAt: { const: 9007199254740991 }
        - properties:
            present: { const: true }
            status: { enum: [temporary_active, temporary_expired] }
            expiresAt: { type: integer, minimum: 0, maximum: 9007199254740990 }
      description: Temporary status is evaluated against the snapshot observation time. A durable hold has no automatic TTL release and establishes no provider finality.
    NativeRecoverySqlUsage:
      type: object
      additionalProperties: false
      required: [present, day, dayRelation, queriesReserved, rowsReadObserved, rowsWrittenObserved, uncertain]
      properties:
        present: { type: boolean }
        day: { type: [string, 'null'], format: date, pattern: '^\d{4}-\d{2}-\d{2}$' }
        dayRelation: { type: string, enum: [none, past, current, future] }
        queriesReserved: { type: integer, minimum: 0, maximum: 9007199254740991 }
        rowsReadObserved: { type: integer, minimum: 0, maximum: 9007199254740991 }
        rowsWrittenObserved: { type: integer, minimum: 0, maximum: 9007199254740991 }
        uncertain: { type: boolean }
      allOf:
        - if: { properties: { present: { const: false } } }
          then:
            properties:
              day: { type: 'null' }
              dayRelation: { const: none }
              queriesReserved: { const: 0 }
              rowsReadObserved: { const: 0 }
              rowsWrittenObserved: { const: 0 }
              uncertain: { const: false }
          else:
            properties:
              day: { type: string }
              dayRelation: { enum: [past, current, future] }
      description: Latest retained sample, not complete history or verified provider charges. Unknown usage blocks SQL across day changes until explicit reconciliation.
    NativeRecoverySql:
      type: object
      additionalProperties: false
      required: [registered, state, providerBindingRecorded, lease, usage, reconciliationRequired, operation]
      properties:
        registered: { type: boolean }
        state: { type: string, enum: [absent, provisioning, ready, deleting] }
        providerBindingRecorded: { type: boolean }
        lease: { $ref: '#/components/schemas/NativeRecoveryLease' }
        usage: { $ref: '#/components/schemas/NativeRecoverySqlUsage' }
        reconciliationRequired: { type: boolean, description: True for a durable lease or any retained uncertain SQL usage sample, including a prior day. }
        operation: { $ref: '#/components/schemas/NativeRecoveryOperation' }
    NativeRecoveryKv:
      type: object
      additionalProperties: false
      required: [registered, state, providerBindingRecorded, lease, manifest, reconciliationRequired, operation]
      properties:
        registered: { type: boolean }
        state: { type: string, enum: [absent, provisioning, ready, deleting] }
        providerBindingRecorded: { type: boolean }
        lease: { $ref: '#/components/schemas/NativeRecoveryLease' }
        manifest:
          type: object
          additionalProperties: false
          required: [reservedKeys, acknowledgedKeys, unacknowledgedKeys]
          properties:
            reservedKeys: { type: integer, minimum: 0, maximum: 250 }
            acknowledgedKeys: { type: integer, minimum: 0, maximum: 250 }
            unacknowledgedKeys: { type: integer, minimum: 0, maximum: 250 }
          description: Reserved equals acknowledged plus unacknowledged metadata keys. These are not verified provider key counts and shared KV usage is not attributed to this project.
        reconciliationRequired: { type: boolean, description: True when the namespace has a durable lease, including uncertain key mutations. }
        operation: { $ref: '#/components/schemas/NativeRecoveryOperation' }
    NativeRecoverySnapshot:
      allOf:
        - $ref: '#/components/schemas/NativeRecoveryAuthority'
        - type: object
          required: [version, kind, projectId, observedAt, metadataRevision, accessEpoch, evidenceDigest, sql, kv, evidence]
          properties:
            version: { const: 1 }
            kind: { const: stackr-native-recovery-snapshot }
            projectId: { type: string, format: uuid, pattern: '^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$' }
            observedAt: { type: integer, minimum: 0, maximum: 253402300799999, multipleOf: 1000, description: Database UTC observation in Unix milliseconds. }
            metadataRevision: { type: integer, minimum: 1, maximum: 9007199254740991 }
            accessEpoch: { type: integer, minimum: 1, maximum: 9007199254740991 }
            evidenceDigest: { type: string, pattern: '^[a-f0-9]{64}$', description: Opaque content binding of retained private metadata; not issuer authentication or provider evidence. }
            sql: { $ref: '#/components/schemas/NativeRecoverySql' }
            kv: { $ref: '#/components/schemas/NativeRecoveryKv' }
            evidence: { const: 'metadata only; provider not queried' }
      unevaluatedProperties: false
      description: Complete bounded SQL/KV metadata snapshot, excluding private owner/provider identifiers, keys, query text, credentials and payloads. Revisions fence retained metadata changes, including ABA, and do not establish uninterrupted provider history. Authorization/session, metadata/epoch and finite-lease clocks are rechecked after inspection finalization. Final fence reads are excluded overhead from incomplete observations and are never provider billing evidence. Inspection accounting can be written; native service state remains unchanged.
    NativeRecoveryExport:
      type: object
      additionalProperties: false
      required: [version, kind, snapshot, contentDigest, contentBinding, issuerAuthenticated]
      properties:
        version: { const: 1 }
        kind: { const: stackr-native-recovery-export }
        snapshot: { $ref: '#/components/schemas/NativeRecoverySnapshot' }
        contentDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        contentBinding: { const: 'unsigned sha256; not issuer authentication' }
        issuerAuthenticated: { const: false }
      description: Canonical unsigned export; anyone with its contents can recompute its digest. Neither issuer, provider evidence nor approval is authenticated.
    NativeRecoveryReviewBinding:
      type: object
      required: [version, projectId, service, intent, sourceContentDigest, evidenceDigest, metadataRevision, accessEpoch, observedAt, expiresAt, contentBinding, issuerAuthenticated, advisoryOnly, evidenceGaps, noInterveningWorkVerified]
      properties:
        version: { const: 1 }
        projectId: { type: string, format: uuid, pattern: '^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$' }
        service: { type: string, enum: [sql, kv] }
        intent: { type: string, enum: [investigate_hold, reconcile_usage] }
        sourceContentDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        evidenceDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
        metadataRevision: { type: integer, minimum: 1, maximum: 9007199254740991 }
        accessEpoch: { type: integer, minimum: 1, maximum: 9007199254740991 }
        observedAt: { type: integer, minimum: 0, maximum: 253402300799999, multipleOf: 1000 }
        expiresAt: { type: integer, minimum: 0, maximum: 253402300799999, multipleOf: 1000, description: Exactly observedAt plus 60000 milliseconds; packet creation cannot extend expiry. }
        contentBinding: { const: 'unsigned sha256; not issuer authentication' }
        issuerAuthenticated: { const: false }
        advisoryOnly: { const: true }
        evidenceGaps:
          type: array
          minItems: 8
          maxItems: 9
          uniqueItems: true
          items:
            type: string
            enum: [issuer_not_authenticated, metadata_history_incomplete, provider_identity_unverified, operation_kind_unrecorded, dispatch_unrecorded, acknowledgement_unrecorded, provider_finality_unverified, intervening_provider_work_unverified, shared_kv_usage_not_project_attributed, usage_observations_incomplete]
        noInterveningWorkVerified: { const: false }
      allOf:
        - if: { properties: { service: { const: kv } } }
          then: { properties: { intent: { const: investigate_hold } } }
      description: investigate_hold requires a durable lease in the original snapshot; reconcile_usage is SQL-only and requires uncertain usage. Export creation/review must be within 60 seconds of the original observation. This binding is unsigned and grants no approval or execution.
    NativeRecoveryReview:
      allOf:
        - $ref: '#/components/schemas/NativeRecoveryAuthority'
        - $ref: '#/components/schemas/NativeRecoveryReviewBinding'
        - type: object
          required: [kind, reviewDigest]
          properties:
            kind: { const: stackr-native-recovery-review }
            reviewDigest: { type: string, pattern: '^[a-f0-9]{64}$', description: Unsigned SHA-256 binding of this packet without reviewDigest; validated before comparison and not issuer authentication. }
      unevaluatedProperties: false
      description: Direct advisory packet accepted by the operator check route. It is not a server-issued approval or execution credential.
    NativeRecoveryAssessment:
      allOf:
        - $ref: '#/components/schemas/NativeRecoveryAuthority'
        - $ref: '#/components/schemas/NativeRecoveryReviewBinding'
        - type: object
          required: [kind, checkedAt, currentObservedAt, freshSnapshotEvidenceDigest, status, current, reasons]
          properties:
            kind: { const: stackr-native-recovery-assessment }
            checkedAt: { type: integer, minimum: 0, maximum: 253402300799999 }
            currentObservedAt: { type: integer, minimum: 0, maximum: 253402300799999, multipleOf: 1000 }
            freshSnapshotEvidenceDigest: { type: string, pattern: '^[a-f0-9]{64}$' }
            status: { type: string, enum: [current, stale] }
            current: { type: boolean }
            reasons:
              type: array
              maxItems: 10
              uniqueItems: true
              items:
                type: string
                enum: [review_from_future, review_expired, snapshot_from_future, snapshot_expired, snapshot_predates_review, project_changed, evidence_changed, metadata_revision_changed, access_epoch_changed, review_condition_changed]
      unevaluatedProperties: false
      description: HTTP 200 includes both current and stale assessments. A current result only matches fresh retained metadata; history, provider finality and all recovery/billing authorities remain unverified or false. It never releases holds, corrects usage or refunds capacity.
    NativeServiceUsageLease:
      type: object
      additionalProperties: false
      required:
      - present
      - active
      - expiresAt
      properties:
        present:
          type: boolean
        active:
          type: boolean
        expiresAt:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
      description: Stored lease metadata only. Expiry changes this view without proving provider request finality.
    NativeServiceUsageMonthlyOperations:
      type: object
      additionalProperties: false
      required:
      - periodKind
      - period
      - latestSamplePeriod
      - currentPeriod
      - operationsReserved
      - limit
      - remainingOperations
      properties:
        periodKind:
          const: utc-month
        period:
          type: string
          pattern: ^\d{4}-(?:0[1-9]|1[0-2])$
        latestSamplePeriod:
          anyOf:
          - type: string
            pattern: ^\d{4}-(?:0[1-9]|1[0-2])$
          - type: 'null'
        currentPeriod:
          type: boolean
        operationsReserved:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        limit:
          const: 2000
        remainingOperations:
          type: integer
          minimum: 0
          maximum: 2000
      description: Reserved operations for the explicitly labeled current period. A missing or different latest sample normalizes current reservations to zero, not verified
        actual usage. Only one latest source counter row is retained; period history is unavailable.
    NativeServiceUsageDailyOperations:
      type: object
      additionalProperties: false
      required:
      - periodKind
      - period
      - latestSamplePeriod
      - currentPeriod
      - operationsReserved
      - limit
      - remainingOperations
      properties:
        periodKind:
          const: utc-day
        period:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        latestSamplePeriod:
          anyOf:
          - type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
        currentPeriod:
          type: boolean
        operationsReserved:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        limit:
          const: 500
        remainingOperations:
          type: integer
          minimum: 0
          maximum: 500
      description: Reserved operations for the explicitly labeled current period. A missing or different latest sample normalizes current reservations to zero, not verified
        actual usage. Only one latest source counter row is retained; period history is unavailable.
    NativeServiceUsageRecords:
      type: object
      additionalProperties: false
      required:
      - registered
      - inventory
      - usage
      properties:
        registered:
          type: boolean
        inventory:
          type: object
          additionalProperties: false
          required:
          - records
          - limit
          - remainingRecords
          properties:
            records:
              type: integer
              minimum: 0
              maximum: 200
            limit:
              const: 200
            remainingRecords:
              type: integer
              minimum: 0
              maximum: 200
        usage:
          $ref: '#/components/schemas/NativeServiceUsageMonthlyOperations'
    NativeServiceUsageSqlLimits:
      type: object
      additionalProperties: false
      required:
      - dailyQueries
      - dailyWriteRows
      properties:
        dailyQueries:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 1000
          - type: 'null'
        dailyWriteRows:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 100000
          - type: 'null'
      description: Declared configuration limits. Null means unavailable or invalid configuration; these do not establish activation, approval, working credentials or provider
        capacity.
    NativeServiceUsageSqlCounters:
      type: object
      additionalProperties: false
      required:
      - periodKind
      - period
      - latestSamplePeriod
      - currentPeriod
      - queriesReserved
      - rowsReadObserved
      - rowsWrittenObserved
      - uncertain
      - latestSampleUncertain
      - blockedByUncertainty
      - remainingQueries
      - remainingWriteRows
      properties:
        periodKind:
          const: utc-day
        period:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        latestSamplePeriod:
          anyOf:
          - type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
        currentPeriod:
          type: boolean
        queriesReserved:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        rowsReadObserved:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        rowsWrittenObserved:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        uncertain:
          type: boolean
        latestSampleUncertain:
          anyOf:
          - type: boolean
          - type: 'null'
        blockedByUncertainty:
          type: boolean
        remainingQueries:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 1000
          - type: 'null'
        remainingWriteRows:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 100000
          - type: 'null'
      description: Queries are reservations, and rows are an incomplete reported subset. Uncertainty in the latest retained sample makes uncertain and blockedByUncertainty true and both remaining fields null even when the sample is from a prior UTC day. Report, export, offline review and browser preserve this sticky block; current-period zero counters do not establish available headroom or verified zero usage.
    NativeServiceUsageSql:
      type: object
      additionalProperties: false
      required:
      - registered
      - state
      - lease
      - limits
      - usage
      properties:
        registered:
          type: boolean
        state:
          type: string
          enum:
          - absent
          - provisioning
          - ready
          - deleting
        lease:
          $ref: '#/components/schemas/NativeServiceUsageLease'
        limits:
          $ref: '#/components/schemas/NativeServiceUsageSqlLimits'
        usage:
          $ref: '#/components/schemas/NativeServiceUsageSqlCounters'
      description: A stored ready state is metadata, not a live provider health check.
    NativeServiceUsageKvLimits:
      type: object
      additionalProperties: false
      required:
      - maxKeys
      - sharedDailyReads
      - sharedDailyWrites
      properties:
        maxKeys:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 250
          - type: 'null'
        sharedDailyReads:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 4000
          - type: 'null'
        sharedDailyWrites:
          anyOf:
          - type: integer
            minimum: 1
            maximum: 250
          - type: 'null'
      description: Declared limits only. Daily read/write limits are shared-account thresholds; no project-specific consumed or remaining KV operation count is exposed.
    NativeServiceUsageKv:
      type: object
      additionalProperties: false
      required:
      - registered
      - state
      - lease
      - keys
      - limits
      - usage
      properties:
        registered:
          type: boolean
        state:
          type: string
          enum:
          - absent
          - provisioning
          - ready
          - deleting
        lease:
          $ref: '#/components/schemas/NativeServiceUsageLease'
        keys:
          type: object
          additionalProperties: false
          required:
          - reserved
          - acknowledged
          - unacknowledged
          - limit
          - remaining
          properties:
            reserved:
              type: integer
              minimum: 0
              maximum: 250
            acknowledged:
              type: integer
              minimum: 0
              maximum: 250
            unacknowledged:
              type: integer
              minimum: 0
              maximum: 250
            limit:
              type: integer
              minimum: 1
              maximum: 250
            remaining:
              type: integer
              minimum: 0
              maximum: 250
          description: Local manifest reservations and acknowledgements, not verified provider key inventory. A lower configured limit may leave zero remaining headroom.
        limits:
          $ref: '#/components/schemas/NativeServiceUsageKvLimits'
        usage:
          type: object
          additionalProperties: false
          required:
          - projectCountersAvailable
          - accountCountersExcluded
          properties:
            projectCountersAvailable:
              type: boolean
              const: false
            accountCountersExcluded:
              type: boolean
              const: true
    NativeServiceUsageQueues:
      type: object
      additionalProperties: false
      required:
      - limits
      - capacity
      - effective
      - usage
      properties:
        limits:
          type: object
          additionalProperties: false
          required:
          - activeJobs
          - retainedJobs
          - dailyOperations
          - maxAttempts
          properties:
            activeJobs:
              const: 50
            retainedJobs:
              const: 500
            dailyOperations:
              const: 500
            maxAttempts:
              const: 5
        capacity:
          type: object
          additionalProperties: false
          required:
          - activeReservations
          - retainedJobs
          - remainingActiveJobs
          - remainingRetainedJobs
          - sharedPlatformCapacityIncluded
          properties:
            activeReservations:
              type: integer
              minimum: 0
              maximum: 500
            retainedJobs:
              type: integer
              minimum: 0
              maximum: 500
            remainingActiveJobs:
              type: integer
              minimum: 0
              maximum: 50
            remainingRetainedJobs:
              type: integer
              minimum: 0
              maximum: 500
            sharedPlatformCapacityIncluded:
              type: boolean
              const: false
          description: Raw queued/leased reservations include expired jobs until a separate resource operation changes them. Effective expiry does not free capacity; platform-wide
            shared capacity is excluded.
        effective:
          type: object
          additionalProperties: false
          required:
          - queued
          - ready
          - delayed
          - leased
          - completed
          - failed
          - cancelled
          - expired
          properties:
            queued:
              type: integer
              minimum: 0
              maximum: 500
            ready:
              type: integer
              minimum: 0
              maximum: 500
            delayed:
              type: integer
              minimum: 0
              maximum: 500
            leased:
              type: integer
              minimum: 0
              maximum: 500
            completed:
              type: integer
              minimum: 0
              maximum: 500
            failed:
              type: integer
              minimum: 0
              maximum: 500
            cancelled:
              type: integer
              minimum: 0
              maximum: 500
            expired:
              type: integer
              minimum: 0
              maximum: 500
          description: SQL-clock current view. Ready plus delayed equals queued; exhausted expired leases become failed and other expired leases become queued, while expired
            job records remain a separate count.
        usage:
          $ref: '#/components/schemas/NativeServiceUsageDailyOperations'
    NativeServiceUsageFiles:
      type: object
      additionalProperties: false
      required:
      - primaryBackend
      - inventory
      - usage
      properties:
        primaryBackend:
          const: d1
        inventory:
          type: object
          additionalProperties: false
          required:
          - objects
          - bytes
          - limits
          - remainingObjects
          - remainingBytes
          properties:
            objects:
              type: integer
              minimum: 0
              maximum: 40
            bytes:
              type: integer
              minimum: 0
              maximum: 5242880
            limits:
              type: object
              additionalProperties: false
              required:
              - objects
              - bytes
              properties:
                objects:
                  const: 40
                bytes:
                  const: 5242880
            remainingObjects:
              type: integer
              minimum: 0
              maximum: 40
            remainingBytes:
              type: integer
              minimum: 0
              maximum: 5242880
        usage:
          $ref: '#/components/schemas/NativeServiceUsageDailyOperations'
    NativeServiceUsageReport:
      type: object
      additionalProperties: false
      required:
      - version
      - projectId
      - observedAt
      - day
      - month
      - services
      - evidence
      - actualProviderUsageVerified
      - actualProviderChargesVerified
      - billingAuthorized
      - providerActionsAuthorized
      - observationsIncomplete
      - ownerAttributionVerified
      properties:
        version:
          const: 1
        projectId:
          type: string
          format: uuid
          pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
          minLength: 36
          maxLength: 36
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          multipleOf: 1000
          description: SQL UTC observation time in Unix milliseconds, at whole-second resolution.
        day:
          type: string
          format: date
          pattern: ^\d{4}-\d{2}-\d{2}$
        month:
          type: string
          pattern: ^\d{4}-(?:0[1-9]|1[0-2])$
        services:
          type: object
          additionalProperties: false
          required:
          - records
          - sql
          - kv
          - queues
          - files
          properties:
            records:
              $ref: '#/components/schemas/NativeServiceUsageRecords'
            sql:
              $ref: '#/components/schemas/NativeServiceUsageSql'
            kv:
              $ref: '#/components/schemas/NativeServiceUsageKv'
            queues:
              $ref: '#/components/schemas/NativeServiceUsageQueues'
            files:
              $ref: '#/components/schemas/NativeServiceUsageFiles'
        evidence:
          const: metadata only; provider not queried
        actualProviderUsageVerified:
          type: boolean
          const: false
        actualProviderChargesVerified:
          type: boolean
          const: false
        billingAuthorized:
          type: boolean
          const: false
        providerActionsAuthorized:
          type: boolean
          const: false
        observationsIncomplete:
          type: boolean
          const: true
        ownerAttributionVerified:
          type: boolean
          const: false
      description: Complete bounded project metadata with separate counter windows and point-in-time inventory. No contents, values, keys, payloads, query text, resource names,
        owner identities, provider IDs/accounts, tokens or credentials. Legacy counters are project-keyed and can include a previous owner; no measured owner/workspace attribution
        follows. The source services retain only their latest counter period. Over-limit inventories fail closed instead of truncating counts.
    NativeServiceUsageExport:
      type: object
      additionalProperties: false
      required:
      - version
      - kind
      - observedAt
      - report
      - contentBinding
      - issuerAuthenticated
      - actualProviderUsageVerified
      - actualProviderChargesVerified
      - billingAuthorized
      - providerActionsAuthorized
      - contentDigest
      properties:
        version:
          const: 1
        kind:
          const: stackr-project-service-usage
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          multipleOf: 1000
          description: SQL UTC observation time in Unix milliseconds, at whole-second resolution.
        report:
          $ref: '#/components/schemas/NativeServiceUsageReport'
        contentBinding:
          const: unsigned sha256; not issuer authentication
        issuerAuthenticated:
          type: boolean
          const: false
        actualProviderUsageVerified:
          type: boolean
          const: false
        actualProviderChargesVerified:
          type: boolean
          const: false
        billingAuthorized:
          type: boolean
          const: false
        providerActionsAuthorized:
          type: boolean
          const: false
        contentDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
          minLength: 64
          maxLength: 64
      description: Canonical JSON content binding only. SHA-256 covers the canonical sorted-key packet excluding contentDigest; anyone can recompute it. No issuer, source
        evidence, provider measurement or invoice authenticity is established.
    NativeServiceUsageFactWindow:
      oneOf:
      - type: object
        additionalProperties: false
        required:
        - kind
        - observedAt
        properties:
          kind:
            const: instant
          observedAt:
            type: integer
            minimum: 0
            maximum: 9007199254740991
            multipleOf: 1000
            description: SQL UTC observation time in Unix milliseconds, at whole-second resolution.
      - type: object
        additionalProperties: false
        required:
        - kind
        - period
        properties:
          kind:
            const: utc-day
          period:
            type: string
            format: date
            pattern: ^\d{4}-\d{2}-\d{2}$
      - type: object
        additionalProperties: false
        required:
        - kind
        - period
        properties:
          kind:
            const: utc-month
          period:
            type: string
            pattern: ^\d{4}-(?:0[1-9]|1[0-2])$
    NativeServiceUsageMetricFact:
      type: object
      additionalProperties: false
      required:
      - service
      - metric
      - unit
      - quantity
      - quantityKnown
      - window
      - evidenceKind
      - completeness
      - uncertain
      - notes
      properties:
        service:
          type: string
          enum:
          - records
          - sql
          - kv
          - queues
          - files
        metric:
          type: string
          minLength: 1
          maxLength: 80
        unit:
          type: string
          enum:
          - records
          - operations
          - queries
          - rows-read
          - rows-written
          - keys
          - jobs
          - objects
          - bytes
        quantity:
          anyOf:
          - type: integer
            minimum: 0
            maximum: 9007199254740991
          - type: 'null'
        quantityKnown:
          type: boolean
        window:
          $ref: '#/components/schemas/NativeServiceUsageFactWindow'
        evidenceKind:
          type: string
          enum:
          - metadata
          - reservation
          - provider-reported-observation
        completeness:
          const: partial
        uncertain:
          type: boolean
        notes:
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: string
            minLength: 1
            maxLength: 100
      description: A per-project fact with its own window. Missing current samples and unavailable shared KV quantities are null, not verified zero. Manifest and raw-capacity
        quantities describe local metadata, not provider inventory.
      allOf:
      - if:
          properties:
            quantity:
              type: 'null'
          required:
          - quantity
        then:
          properties:
            quantityKnown:
              type: boolean
              const: false
        else:
          properties:
            quantityKnown:
              type: boolean
              const: true
    NativeServiceUsageFacts:
      type: object
      additionalProperties: false
      required:
      - version
      - kind
      - projectId
      - observedAt
      - sourceContentDigest
      - contentBindingValid
      - contentBinding
      - issuerAuthenticated
      - ownerAttributionVerified
      - projectAttributionOnly
      - historicalCoverageComplete
      - aggregation
      - metrics
      - observationsIncomplete
      - actualProviderUsageVerified
      - actualProviderChargesVerified
      - billingAuthorized
      - pricingAuthorized
      - providerActionsAuthorized
      properties:
        version:
          const: 1
        kind:
          const: stackr-project-service-usage-facts
        projectId:
          type: string
          format: uuid
          pattern: ^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$
          minLength: 36
          maxLength: 36
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          multipleOf: 1000
          description: SQL UTC observation time in Unix milliseconds, at whole-second resolution.
        sourceContentDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
          minLength: 64
          maxLength: 64
        contentBindingValid:
          type: boolean
          const: true
        contentBinding:
          const: unsigned sha256; not issuer authentication
        issuerAuthenticated:
          type: boolean
          const: false
        ownerAttributionVerified:
          type: boolean
          const: false
        projectAttributionOnly:
          type: boolean
          const: true
        historicalCoverageComplete:
          type: boolean
          const: false
        aggregation:
          const: separate windows; no combined billing period or cost total
        metrics:
          type: array
          minItems: 15
          maxItems: 15
          items:
            $ref: '#/components/schemas/NativeServiceUsageMetricFact'
        observationsIncomplete:
          type: boolean
          const: true
        actualProviderUsageVerified:
          type: boolean
          const: false
        actualProviderChargesVerified:
          type: boolean
          const: false
        billingAuthorized:
          type: boolean
          const: false
        pricingAuthorized:
          type: boolean
          const: false
        providerActionsAuthorized:
          type: boolean
          const: false
      description: Offline service:review output, not an HTTP action or invoice input. Facts retain monthly, daily and inventory windows separately. No reconstruction of source
        history, cost total or measured workspace/owner attribution is performed.
    StorageControlObservations:
      type: object
      additionalProperties: false
      required:
      - queries
      - queriesWithRowCounts
      - rowsRead
      - rowsWritten
      properties:
        queries:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        queriesWithRowCounts:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        rowsRead:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        rowsWritten:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      description: Statements submitted through the measured binding, not verified executions or billed calls. queriesWithRowCounts counts only replies exposing valid meta.rows_read
        and meta.rows_written; first()/raw() and missing metadata contribute no trusted row totals. Missing row counts stay unknown.
    StorageControlFinished:
      type: object
      additionalProperties: false
      required:
      - succeeded
      - failed
      - uncertain
      properties:
        succeeded:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        failed:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        uncertain:
          type: integer
          minimum: 0
          maximum: 9007199254740991
    StorageControlAllowance:
      type: object
      additionalProperties: false
      required:
      - requests
      - units
      - remainingRequests
      - remainingUnits
      - limits
      - activeHandlers
      - activeSlots
      properties:
        requests:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        units:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        remainingRequests:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        remainingUnits:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        limits:
          type: object
          additionalProperties: false
          required:
          - requests
          - units
          - activeHandlers
          properties:
            requests:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            units:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            activeHandlers:
              type: integer
              minimum: 1
              maximum: 3
        activeHandlers:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        activeSlots:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      description: Fixed inspection work allowance. Units are not database rows or monetary costs. Daily counters reset on the SQL UTC date; active slots can remain until their
        lease expires.
    StorageControlKindUsage:
      type: object
      additionalProperties: false
      required:
      - kind
      - requests
      - units
      - finished
      - measurements
      - observedOverflow
      - observed
      properties:
        kind:
          enum:
          - activity
          - review_list
          - review_detail
          - object_review
          - review_check
          - review_write
          - usage
        requests:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        units:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        finished:
          $ref: '#/components/schemas/StorageControlFinished'
        measurements:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        observedOverflow:
          type: boolean
        observed:
          $ref: '#/components/schemas/StorageControlObservations'
    StorageControlSummary:
      type: object
      additionalProperties: false
      required:
      - requests
      - units
      - finished
      - measurements
      - observedOverflow
      - observed
      - byKind
      properties:
        requests:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        units:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        finished:
          $ref: '#/components/schemas/StorageControlFinished'
        measurements:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        observedOverflow:
          type: boolean
        observed:
          $ref: '#/components/schemas/StorageControlObservations'
        byKind:
          type: array
          maxItems: 7
          items:
            $ref: '#/components/schemas/StorageControlKindUsage'
      description: Admitted work and finalized statement observations for a selected day/scope. Saturated observations are marked by observedOverflow; all observations remain incomplete.
    StorageControlPlatformLane:
      type: object
      additionalProperties: false
      required:
      - allowance
      - finished
      - measurements
      - observedOverflow
      - observed
      - byKind
      properties:
        allowance:
          $ref: '#/components/schemas/StorageControlAllowance'
        finished:
          $ref: '#/components/schemas/StorageControlFinished'
        measurements:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        observedOverflow:
          type: boolean
        observed:
          $ref: '#/components/schemas/StorageControlObservations'
        byKind:
          type: array
          maxItems: 7
          items:
            $ref: '#/components/schemas/StorageControlKindUsage'
    StorageControlOwnerUsage:
      type: object
      additionalProperties: false
      required:
      - version
      - day
      - observedAt
      - currentInspectionFinalized
      - observationsIncomplete
      - actualProviderChargesVerified
      - evidence
      - scope
      - allowance
      - project
      - observedOverflow
      - meteringOverheadIncluded
      - billingAuthorized
      - providerActionsAuthorized
      properties:
        version:
          const: 1
        day:
          type: string
          format: date
          description: SQL UTC reservation day.
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          multipleOf: 1000
        currentInspectionFinalized:
          const: false
        observationsIncomplete:
          const: true
        actualProviderChargesVerified:
          const: false
        evidence:
          const: control-plane inspection reservations and submitted D1 statement observations; metering overhead excluded
        scope:
          const: owner
        allowance:
          $ref: '#/components/schemas/StorageControlAllowance'
        project:
          $ref: '#/components/schemas/StorageControlSummary'
        observedOverflow:
          type: boolean
        meteringOverheadIncluded:
          const: false
        billingAuthorized:
          const: false
        providerActionsAuthorized:
          const: false
      description: Current owner allowance shared across projects, plus this project history keyed to its captured owner. No private identifiers or SQL text. This HTTP usage request
        reserves first; its current-day reservation can be visible while its statement observations await finalization. The HTTP wrapper writes inspection admission/observation
        metadata, with no resource/provider mutation.
    StorageControlOperatorUsage:
      type: object
      additionalProperties: false
      required:
      - version
      - day
      - observedAt
      - currentInspectionFinalized
      - observationsIncomplete
      - actualProviderChargesVerified
      - evidence
      - scope
      - lanes
      - ownPrincipalAllowance
      - observedOverflow
      - meteringOverheadIncluded
      - billingAuthorized
      - providerActionsAuthorized
      properties:
        version:
          const: 1
        day:
          type: string
          format: date
          description: SQL UTC reservation day.
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          multipleOf: 1000
        currentInspectionFinalized:
          const: false
        observationsIncomplete:
          const: true
        actualProviderChargesVerified:
          const: false
        evidence:
          const: control-plane inspection reservations and submitted D1 statement observations; metering overhead excluded
        scope:
          const: platform
        lanes:
          type: object
          additionalProperties: false
          required:
          - owner
          - operator
          properties:
            owner:
              $ref: '#/components/schemas/StorageControlPlatformLane'
            operator:
              $ref: '#/components/schemas/StorageControlPlatformLane'
        ownPrincipalAllowance:
          $ref: '#/components/schemas/StorageControlAllowance'
        observedOverflow:
          type: boolean
        meteringOverheadIncluded:
          const: false
        billingAuthorized:
          const: false
        providerActionsAuthorized:
          const: false
      description: Both platform lanes and the current authenticated operator principal allowance; no principal hashes or private identifiers. The HTTP wrapper writes inspection
        admission/observation metadata, with no resource/provider mutation.
    StorageControlCostAggregate:
      type: object
      additionalProperties: true
      required:
      - requests
      - units
      - finished
      - observed
      properties:
        requests:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        units:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        finished:
          $ref: '#/components/schemas/StorageControlFinished'
        observed:
          $ref: '#/components/schemas/StorageControlObservations'
        observedOverflow:
          const: false
    StorageControlCostLane:
      type: object
      additionalProperties: true
      required:
      - allowance
      - finished
      - observed
      properties:
        allowance:
          type: object
          additionalProperties: true
          required:
          - requests
          - units
          properties:
            requests:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            units:
              type: integer
              minimum: 0
              maximum: 9007199254740991
        finished:
          $ref: '#/components/schemas/StorageControlFinished'
        observed:
          $ref: '#/components/schemas/StorageControlObservations'
        observedOverflow:
          const: false
    StorageControlCostUsage:
      type: object
      additionalProperties: true
      required:
      - version
      - day
      - observedAt
      - scope
      - observationsIncomplete
      - actualProviderChargesVerified
      - evidence
      properties:
        version:
          const: 1
        day:
          type: string
          format: date
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        scope:
          enum:
          - owner
          - platform
        observationsIncomplete:
          const: true
        actualProviderChargesVerified:
          const: false
        evidence:
          type: string
          minLength: 1
          maxLength: 2048
      description: Minimum explicitly unverified aggregate input for offline scenario arithmetic. Additional usage metadata is ignored and never echoed. Use a selected scope/day
        and allocate allowances without double counting.
    StorageControlCostAssumptions:
      type: object
      additionalProperties: false
      required:
      - currency
      - rowsReadMicrosPerMillion
      - rowsWrittenMicrosPerMillion
      - includedRowsRead
      - includedRowsWritten
      - allocatedFixedMicros
      - perRequestOverheadMicros
      - unmeasuredReserveMicros
      - budgetMicros
      properties:
        currency:
          const: USD
        rowsReadMicrosPerMillion:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: User-declared USD micro-dollar rate per million observed read rows; not a verified current provider quote.
        rowsWrittenMicrosPerMillion:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: User-declared USD micro-dollar rate per million observed written rows; not a verified current provider quote.
        includedRowsRead:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        includedRowsWritten:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        allocatedFixedMicros:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        perRequestOverheadMicros:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        unmeasuredReserveMicros:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        budgetMicros:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      description: Explicit nonnegative safe-integer assumptions. Allocate included rows and fixed costs to the selected day/scope without duplicate allocation. Unmeasured reserve
        and per-request overhead are caller assumptions, not verified missing costs.
    StorageControlCostInput:
      type: object
      additionalProperties: false
      required:
      - usage
      - selection
      - assumptions
      properties:
        usage:
          $ref: '#/components/schemas/StorageControlCostUsage'
        selection:
          enum:
          - project
          - platform-owner
          - platform-operator
        assumptions:
          $ref: '#/components/schemas/StorageControlCostAssumptions'
      description: Offline storage:costs input, not an HTTP action. The file is at most 256 KiB and must be regular local JSON. User-declared prices, allowances and usage evidence
        do not establish actual charges or authorization.
      oneOf:
      - properties:
          selection:
            const: project
          usage:
            allOf:
            - $ref: '#/components/schemas/StorageControlCostUsage'
            - required:
              - project
              properties:
                scope:
                  const: owner
                project:
                  $ref: '#/components/schemas/StorageControlCostAggregate'
      - properties:
          selection:
            const: platform-owner
          usage:
            allOf:
            - $ref: '#/components/schemas/StorageControlCostUsage'
            - required:
              - lanes
              properties:
                scope:
                  const: platform
                lanes:
                  type: object
                  required:
                  - owner
                  properties:
                    owner:
                      $ref: '#/components/schemas/StorageControlCostLane'
      - properties:
          selection:
            const: platform-operator
          usage:
            allOf:
            - $ref: '#/components/schemas/StorageControlCostUsage'
            - required:
              - lanes
              properties:
                scope:
                  const: platform
                lanes:
                  type: object
                  required:
                  - operator
                  properties:
                    operator:
                      $ref: '#/components/schemas/StorageControlCostLane'
    StorageControlCostScenario:
      type: object
      additionalProperties: false
      required:
      - version
      - kind
      - currency
      - day
      - observedAt
      - selection
      - usage
      - coverage
      - assumptions
      - scenario
      - status
      - rateEvidence
      - usageEvidence
      - queryEvidence
      - reservationEvidence
      - observationsIncomplete
      - actualProviderChargesVerified
      - completeUsageVerified
      - billingAuthorized
      - pricingAuthorized
      - refundAuthorized
      - providerActionsAuthorized
      properties:
        version:
          const: 1
        kind:
          const: storage-control-cost-scenario
        currency:
          const: USD
        day:
          type: string
          format: date
        observedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        selection:
          enum:
          - project
          - platform-owner
          - platform-operator
        usage:
          type: object
          additionalProperties: false
          required:
          - requests
          - reservationUnits
          - finished
          - observed
          properties:
            requests:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            reservationUnits:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            finished:
              $ref: '#/components/schemas/StorageControlFinished'
            observed:
              $ref: '#/components/schemas/StorageControlObservations'
        coverage:
          type: object
          additionalProperties: false
          required:
          - queries
          - queriesWithRowCounts
          - missingRowCounts
          - observedOverflow
          - rowCountCoverageBps
          properties:
            queries:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            queriesWithRowCounts:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            missingRowCounts:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            observedOverflow:
              const: false
            rowCountCoverageBps:
              type:
              - integer
              - 'null'
              minimum: 0
              maximum: 10000
        assumptions:
          $ref: '#/components/schemas/StorageControlCostAssumptions'
        scenario:
          type: object
          additionalProperties: false
          required:
          - payableObservedReadRows
          - payableObservedWrittenRows
          - observedReadRowsComponentMicros
          - observedWrittenRowsComponentMicros
          - declaredRequestOverheadMicros
          - allocatedFixedMicros
          - unmeasuredReserveMicros
          - scenarioEstimateMicros
          - budgetMicros
          - exceedsDeclaredBudget
          properties:
            payableObservedReadRows:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            payableObservedWrittenRows:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            observedReadRowsComponentMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            observedWrittenRowsComponentMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            declaredRequestOverheadMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            allocatedFixedMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            unmeasuredReserveMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            scenarioEstimateMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            budgetMicros:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            exceedsDeclaredBudget:
              type: boolean
        status:
          enum:
          - scenario_exceeds_budget
          - scenario_within_budget
        rateEvidence:
          const: user-supplied assumptions; rates and included allowances are not independently verified
        usageEvidence:
          const: incomplete observed rows; authentication, admission, finalization and late activity may be excluded
        queryEvidence:
          const: submitted SQL statements; not verified executions or provider-billed calls
        reservationEvidence:
          const: fixed inspection work weights; not database rows or monetary costs
        observationsIncomplete:
          const: true
        actualProviderChargesVerified:
          const: false
        completeUsageVerified:
          const: false
        billingAuthorized:
          const: false
        pricingAuthorized:
          const: false
        refundAuthorized:
          const: false
        providerActionsAuthorized:
          const: false
      description: Offline safe-integer scenario with conservatively rounded observed-row components and declared overhead/reserves. Valid arithmetic exits 0 even above budget;
        invalid input exits 1. A within-budget scenario proves no actual provider charges, spending cap, complete usage, profit or competitive price.
    ObjectReviewIssueRequest:
      type: object
      additionalProperties: false
      required:
      - requestId
      properties:
        requestId:
          type: string
          format: uuid
          description: Retry key scoped to the authenticated operator principal. Same target and requested action reuse the original immutable record and expiry.
        action:
          $ref: '#/components/schemas/ObjectReconciliationAction'
      description: Create from fresh server metadata only. Caller-supplied packet, owner context, principal, confirmations and expiry are rejected.
    ObjectReviewConfirmationRequest:
      type: object
      additionalProperties: false
      required:
      - expectedRevision
      - proposalDigest
      - confirmed
      properties:
        expectedRevision:
          type: integer
          minimum: 1
          maximum: 18
        proposalDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
        confirmed:
          type: boolean
          description: true records this authenticated channel acknowledgement; false revokes it. No execution authority is granted.
    ObjectReviewWithdrawalRequest:
      type: object
      additionalProperties: false
      required:
      - expectedRevision
      - proposalDigest
      properties:
        expectedRevision:
          type: integer
          minimum: 1
          maximum: 18
        proposalDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
    ObjectReviewRecord:
      type: object
      additionalProperties: false
      required:
      - version
      - recordId
      - requestId
      - revision
      - attemptId
      - projectId
      - backendId
      - action
      - packet
      - createdAt
      - expiresAt
      - withdrawnAt
      - expectedBytes
      - reviewState
      - current
      - checkedAt
      - reasonCodes
      - serverRecordVerified
      - confirmations
      - events
      - evidence
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      properties:
        version:
          const: 1
        recordId:
          type: string
          format: uuid
        requestId:
          type: string
          format: uuid
        revision:
          type: integer
          minimum: 1
          maximum: 18
        attemptId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        backendId:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,63}$
        action:
          $ref: '#/components/schemas/ObjectReconciliationAction'
        packet:
          $ref: '#/components/schemas/ObjectReconciliationProposal'
        createdAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        expiresAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        withdrawnAt:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 9007199254740991
        fileKey:
          type: string
          minLength: 1
          maxLength: 128
          description: Present only in current owner-session views to identify the staged copy; never returned to operator routes.
        expectedBytes:
          type: integer
          minimum: 0
          maximum: 1048576
        reviewState:
          enum:
          - unchecked
          - open
          - partially_confirmed
          - confirmed
          - stale
          - expired
          - withdrawn
          - unavailable
          description: confirmed means both authenticated role channels recorded acknowledgements for current evidence. It grants no execution or approval and does not prove distinct
            human reviewers.
        current:
          type: boolean
          description: Current at checkedAt after fresh metadata and authorization comparison. List summaries leave this false.
        checkedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        reasonCodes:
          type: array
          items:
            type: string
        serverRecordVerified:
          const: true
          description: The server looked up its persisted record. An exported JSON copy is not a portable authenticated approval or execution credential.
        confirmations:
          type: object
          additionalProperties: false
          required:
          - owner
          - operator
          properties:
            owner:
              type: object
              additionalProperties: false
              required:
              - recordedAt
              - effective
              properties:
                recordedAt:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 9007199254740991
                effective:
                  type: boolean
            operator:
              type: object
              additionalProperties: false
              required:
              - recordedAt
              - effective
              properties:
                recordedAt:
                  type:
                  - integer
                  - 'null'
                  minimum: 0
                  maximum: 9007199254740991
                effective:
                  type: boolean
        events:
          type: array
          maxItems: 18
          items:
            type: object
            additionalProperties: false
            required:
            - role
            - action
            - at
            - revision
            properties:
              role:
                enum:
                - owner
                - operator
              action:
                enum:
                - issued
                - confirmed
                - revoked
                - withdrawn
              at:
                type: integer
                minimum: 0
                maximum: 9007199254740991
              revision:
                type: integer
                minimum: 1
                maximum: 18
        evidence:
          const: authenticated role acknowledgements; separate execution review required
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
      description: Persisted server-created metadata review receipt. Target, packet, digest and expiry are immutable. No private owner identity, operator principal hash, provider
        account/bucket, checksum or claim token is returned. All seven authority flags remain false, including for confirmed records.
    ObjectOperatorReviewRecord:
      allOf:
      - $ref: '#/components/schemas/ObjectReviewRecord'
      - not:
          required:
          - fileKey
    ObjectOwnerReviewRecord:
      allOf:
      - $ref: '#/components/schemas/ObjectReviewRecord'
      - required:
        - fileKey
    ObjectOperatorReviewList:
      type: object
      additionalProperties: false
      required:
      - version
      - records
      - nextCursor
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      properties:
        version:
          const: 1
        records:
          type: array
          maxItems: 25
          items:
            allOf:
            - $ref: '#/components/schemas/ObjectOperatorReviewRecord'
            - properties:
                current:
                  const: false
                reviewState:
                  enum:
                  - unchecked
                  - expired
                  - withdrawn
                confirmations:
                  properties:
                    owner:
                      properties:
                        effective:
                          const: false
                    operator:
                      properties:
                        effective:
                          const: false
        nextCursor:
          type:
          - string
          - 'null'
          maxLength: 54
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
      description: Private newest-first record summaries. Open detail for a fresh evidence check; pagination never confirms a record.
    ObjectOwnerReviewList:
      type: object
      additionalProperties: false
      required:
      - version
      - records
      - nextCursor
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      properties:
        version:
          const: 1
        records:
          type: array
          maxItems: 25
          items:
            allOf:
            - $ref: '#/components/schemas/ObjectOwnerReviewRecord'
            - properties:
                current:
                  const: false
                reviewState:
                  enum:
                  - unchecked
                  - expired
                  - withdrawn
                confirmations:
                  properties:
                    owner:
                      properties:
                        effective:
                          const: false
                    operator:
                      properties:
                        effective:
                          const: false
        nextCursor:
          type:
          - string
          - 'null'
          maxLength: 54
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
      description: Private newest-first record summaries. Open detail for a fresh evidence check; pagination never confirms a record.
    ObjectReconciliationAction:
      type: string
      enum:
      - retain_hold
      - review_writer_finality
      - wait_for_claims
      - inspect_references
      - review_cleanup_retry
      - no_action
      description: Advisory review only. review_cleanup_retry does not reset a retry allowance, dispatch deletion or release capacity.
    ObjectReconciliationClaim:
      type: object
      additionalProperties: false
      required:
      - present
      - active
      - expiresAt
      properties:
        present:
          type: boolean
        active:
          type: boolean
        expiresAt:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 9007199254740991
    ObjectReconciliationObservations:
      type: object
      additionalProperties: false
      required:
      - putInvocations
      - getInvocations
      - headInvocations
      - deleteInvocations
      - readBytes
      - writeBytes
      properties:
        putInvocations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        getInvocations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        headInvocations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        deleteInvocations:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        readBytes:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        writeBytes:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      description: Application observations at finalization may omit late activity or retries; not provider-billed actuals.
    ObjectReconciliationSnapshot:
      type: object
      additionalProperties: false
      required:
      - version
      - scope
      - attemptId
      - projectId
      - backendId
      - observedAt
      - evidenceDigest
      - revision
      - state
      - uncertain
      - cleanupRequested
      - expectedBytes
      - reason
      - createdAt
      - updatedAt
      - writer
      - cleanup
      - source
      - backend
      - references
      - operations
      - primaryBackend
      - evidence
      - actualProviderUsageVerified
      - billingAuthorized
      properties:
        version:
          const: 1
        scope:
          enum:
          - operator
          - project
        attemptId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        backendId:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,63}$
        observedAt:
          type: integer
          multipleOf: 1000
          minimum: 0
          maximum: 9007199254740991
          description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        evidenceDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
        revision:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Monotonic lifecycle and reference review revision; no provider finality claim.
        state:
          enum:
          - pending
          - writing
          - verified
          - cleanup
          - held
          - cleaned
        uncertain:
          type: boolean
        cleanupRequested:
          type: boolean
        expectedBytes:
          type: integer
          minimum: 0
          maximum: 1048576
        reason:
          type: string
          maxLength: 64
          description: Reason code or redacted/unspecified; no raw private reason text.
        createdAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        updatedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        writer:
          $ref: '#/components/schemas/ObjectReconciliationClaim'
        cleanup:
          type: object
          additionalProperties: false
          required:
          - present
          - active
          - expiresAt
          - attempts
          - nextAt
          properties:
            present:
              type: boolean
            active:
              type: boolean
            expiresAt:
              type:
              - integer
              - 'null'
              minimum: 0
              maximum: 9007199254740991
            attempts:
              type: integer
              minimum: 0
              maximum: 3
            nextAt:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        source:
          type: object
          additionalProperties: false
          required:
          - exists
          - revisionMatches
          - sizeMatches
          - authorityCurrent
          properties:
            exists:
              type: boolean
            revisionMatches:
              type: boolean
            sizeMatches:
              type: boolean
            authorityCurrent:
              type: boolean
        backend:
          type: object
          additionalProperties: false
          required:
          - registered
          - enabled
          - revision
          properties:
            registered:
              type: boolean
            enabled:
              type: boolean
            revision:
              type:
              - integer
              - 'null'
              minimum: 1
              maximum: 9007199254740991
        references:
          type: object
          additionalProperties: false
          required:
          - pointerCount
          - activePins
          - expiredPins
          - maxPinExpiry
          properties:
            pointerCount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            activePins:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            expiredPins:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            maxPinExpiry:
              type:
              - integer
              - 'null'
              minimum: 0
              maximum: 9007199254740991
        operations:
          type: object
          additionalProperties: false
          required:
          - count
          - activeHandlers
          - unexpiredSlots
          - plannedCalls
          - reservedBytes
          - observed
          - observationsMayBeIncomplete
          - providerBillingVerified
          properties:
            count:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            activeHandlers:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            unexpiredSlots:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            plannedCalls:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            reservedBytes:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            observed:
              $ref: '#/components/schemas/ObjectReconciliationObservations'
            observationsMayBeIncomplete:
              const: true
            providerBillingVerified:
              const: false
        primaryBackend:
          const: d1
        evidence:
          const: metadata only; provider not queried
        actualProviderUsageVerified:
          const: false
        billingAuthorized:
          const: false
      description: Redacted current SQL metadata. Private immutable identity, claims, references, source/account status, backend revision and retained operations enter
        evidenceDigest without disclosing keys, content checksums, identities, claim tokens, provider accounts or buckets. The digest is content binding, not provider
        attestation.
    ObjectReconciliationAssessment:
      type: object
      additionalProperties: false
      required:
      - version
      - attemptId
      - recommendedAction
      - availableActions
      - reasons
      - requirements
      - quotaRemainsHeld
      - evidence
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      properties:
        version:
          const: 1
        attemptId:
          type: string
          format: uuid
        recommendedAction:
          $ref: '#/components/schemas/ObjectReconciliationAction'
        availableActions:
          type: array
          items:
            $ref: '#/components/schemas/ObjectReconciliationAction'
        reasons:
          type: array
          items:
            type: string
        requirements:
          type: array
          items:
            type: string
        quotaRemainsHeld:
          type: boolean
        evidence:
          const: advisory metadata review; provider not queried
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
      description: Unknown writes allow only retaining a hold or independent writer-finality review. Matching bytes, absence and lease expiry are not provider finality
        evidence.
    ObjectReconciliationProposal:
      type: object
      additionalProperties: false
      required:
      - version
      - kind
      - attemptId
      - projectId
      - backendId
      - lifecycleRevision
      - evidenceDigest
      - action
      - observedAt
      - issuedAt
      - expiresAt
      - contentBinding
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      - proposalDigest
      properties:
        version:
          const: 1
        kind:
          const: stackr-object-reconciliation-review
        attemptId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        backendId:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,63}$
        lifecycleRevision:
          type: integer
          minimum: 1
          maximum: 9007199254740991
        evidenceDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
        action:
          $ref: '#/components/schemas/ObjectReconciliationAction'
        observedAt:
          type: integer
          multipleOf: 1000
          minimum: 0
          maximum: 9007199254740991
          description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        issuedAt:
          type: integer
          multipleOf: 1000
          minimum: 0
          maximum: 9007199254740991
          description: Packet creation time, floored to SQL-compatible seconds; unsigned and not authenticated server issuance.
        expiresAt:
          type: integer
          multipleOf: 1000
          minimum: 0
          maximum: 9007199254740991
          description: Exactly observedAt + 300000. Rechecking or recreating an old snapshot cannot extend this lifetime.
        contentBinding:
          const: unsigned sha256; not issuer authentication or approval
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
        proposalDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
      description: Unsigned advisory content binding only. Anyone with a snapshot can create a matching packet. It grants no owner/operator confirmation, approval or
        execution authority. Creation requires a snapshot at most 60 seconds old.
    ObjectReconciliationValidation:
      type: object
      additionalProperties: false
      required:
      - version
      - valid
      - reasons
      - attemptId
      - checkedAt
      - evidence
      - executable
      - approvalGranted
      - providerFinalityVerified
      - quotaReleaseAuthorized
      - cleanupRetryAuthorized
      - publicationAuthorized
      - billingAuthorized
      properties:
        version:
          const: 1
        valid:
          type: boolean
        reasons:
          type: array
          items:
            type: string
        attemptId:
          type: string
          format: uuid
        checkedAt:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Unix milliseconds; authoritative server snapshots use SQL-clock seconds represented as milliseconds.
        evidence:
          const: unsigned packet checked against supplied current metadata; not authenticated issuance
        executable:
          const: false
        approvalGranted:
          const: false
        providerFinalityVerified:
          const: false
        quotaReleaseAuthorized:
          const: false
        cleanupRetryAuthorized:
          const: false
        publicationAuthorized:
          const: false
        billingAuthorized:
          const: false
      description: Current-equivalence check at the snapshot observation. valid true does not prove server issuance, response-time freshness, provider finality or approval.
    ObjectReconciliationReview:
      type: object
      additionalProperties: false
      required:
      - snapshot
      - assessment
      - proposal
      properties:
        snapshot:
          $ref: '#/components/schemas/ObjectReconciliationSnapshot'
        assessment:
          $ref: '#/components/schemas/ObjectReconciliationAssessment'
        proposal:
          $ref: '#/components/schemas/ObjectReconciliationProposal'
    ObjectLifecycleCounts:
      type: object
      required: [objects, bytes]
      properties:
        objects: { type: integer, minimum: 0 }
        bytes: { type: integer, minimum: 0 }
    ObjectLifecycleStates:
      type: object
      required: [pending, writing, verified, cleanup, held, cleaned]
      properties:
        pending: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        writing: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        verified: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        cleanup: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        held: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        cleaned: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
    ProjectObjectOverview:
      type: object
      required: [version, scope, observedAt, primaryBackend, evidence, actualProviderUsageVerified, billingAuthorized, states, quotaHeld, limits, publishedPointers, readPins, work, heldReasons, heldReasonsTruncated, backends, backendGroupsTotal, backendGroupsTruncated]
      properties:
        version: { const: 1 }
        scope: { enum: [project, platform] }
        observedAt: { type: integer, minimum: 0, description: SQL-clock Unix milliseconds }
        primaryBackend: { const: d1 }
        evidence: { const: 'metadata only; provider not queried' }
        actualProviderUsageVerified: { const: false }
        billingAuthorized: { const: false }
        states: { $ref: '#/components/schemas/ObjectLifecycleStates' }
        quotaHeld:
          allOf:
            - $ref: '#/components/schemas/ObjectLifecycleCounts'
          description: All lifecycle reservations except cleaned entries; not provider-billed usage.
        limits:
          type: object
          properties:
            perProject: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
            platform: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
            backendGroups: { const: 100 }
            heldReasons: { const: 20 }
            queue: { const: 25 }
        publishedPointers: { type: integer, minimum: 0 }
        readPins:
          type: object
          properties:
            active: { type: integer, minimum: 0 }
            expired: { type: integer, minimum: 0 }
            activeGroups: { type: integer, minimum: 0 }
        work:
          type: object
          properties:
            activeWriters: { type: integer, minimum: 0 }
            expiredWriters: { type: integer, minimum: 0 }
            cleanupDue: { type: integer, minimum: 0 }
            cleanupLeased: { type: integer, minimum: 0 }
            held: { type: integer, minimum: 0 }
        heldReasons:
          type: array
          maxItems: 20
          items:
            type: object
            properties:
              reason: { type: string, maxLength: 64, description: Bounded reason code or redacted/unspecified }
              objects: { type: integer, minimum: 0 }
              bytes: { type: integer, minimum: 0 }
        heldReasonsTruncated: { type: boolean }
        backends:
          type: array
          maxItems: 100
          items:
            type: object
            properties:
              backendId: { type: string, description: Private immutable routing identifier; not a provider identity attestation }
              registered: { type: boolean }
              enabled: { type: boolean }
              states: { $ref: '#/components/schemas/ObjectLifecycleStates' }
              quotaHeld: { $ref: '#/components/schemas/ObjectLifecycleCounts' }
        backendGroupsTotal: { type: integer, minimum: 0 }
        backendGroupsTruncated: { type: boolean }
    ObjectLifecycleQueueEntry:
      type: object
      description: Redacted metadata only. File/object keys, contents, owner identities, credentials and lease tokens are excluded.
      required: [attemptId, projectId, backendId, state, reason, expectedBytes, createdAt, updatedAt, writerUntil, cleanupUntil, nextCleanupAt, cleanupAttempts, uncertain, ageMs]
      properties:
        attemptId: { type: string, format: uuid }
        projectId: { type: string, format: uuid }
        backendId: { type: string }
        state: { enum: [pending, writing, verified, cleanup, held, cleaned] }
        reason: { type: string, maxLength: 64 }
        expectedBytes: { type: integer, minimum: 0 }
        createdAt: { type: integer, minimum: 0, description: Unix milliseconds }
        updatedAt: { type: integer, minimum: 0, description: Unix milliseconds }
        writerUntil: { type: [integer, 'null'], minimum: 0 }
        cleanupUntil: { type: [integer, 'null'], minimum: 0 }
        nextCleanupAt: { type: [integer, 'null'], minimum: 0 }
        cleanupAttempts: { type: integer, minimum: 0 }
        uncertain: { type: boolean }
        ageMs: { type: integer, minimum: 0 }
    PrivateFileSnapshot:
      type: object
      additionalProperties: false
      required: [format, version, fileCount, totalBytes, files]
      properties:
        format: { const: stackr-private-files }
        version: { const: 1 }
        fileCount: { type: integer, minimum: 0, maximum: 40 }
        totalBytes: { type: integer, minimum: 0, maximum: 5242880 }
        files:
          type: array
          maxItems: 40
          items:
            type: object
            additionalProperties: false
            required: [key, size, revision, etag, updatedAt, sha256, encoding, content]
            properties:
              key: { type: string, maxLength: 128 }
              size: { type: integer, minimum: 0, maximum: 1048576 }
              revision: { type: string, format: uuid }
              etag: { type: string, description: Quoted original revision }
              updatedAt: { type: integer, minimum: 0 }
              sha256: { type: string, pattern: '^[a-f0-9]{64}$' }
              encoding: { const: base64 }
              content: { type: string, contentEncoding: base64, description: Canonical base64 of the original file bytes }
    StaticRouteTestResult:
      type: object
      required: [path, kind, status]
      properties:
        path: { type: string }
        kind: { type: string, enum: [redirect, directory, rewrite, asset, fallback, missing, blocked, managed] }
        status: { type: [integer, 'null'] }
        location: { type: string, description: App-relative redirect location }
        file: { type: string, description: Archive-relative file path }
        finalStatus: { type: [integer, 'null'], description: Outcome after following the bounded local redirect chain }
        finalFile: { type: string, description: Archive-relative file reached after a local redirect }
        hidesFile: { const: true }
        reason: { type: string }
        headers:
          type: object
          additionalProperties: { type: string }
    RoutingImportRedirect:
      type: object
      required: [from, to, status]
      properties:
        from: { type: string, maxLength: 200 }
        to: { type: string, maxLength: 200 }
        status: { type: integer, enum: [301, 302, 307, 308] }
    RoutingImportRewrite:
      type: object
      required: [from, to]
      properties:
        from: { type: string, maxLength: 200 }
        to: { type: string, maxLength: 200 }
    RoutingImportReview:
      type: object
      required: [live, suggestions, changes, issues]
      properties:
        live: { type: boolean, description: The project has a published release serving traffic. }
        suggestions:
          type: object
          required: [redirects, rewrites, headers]
          properties:
            redirects:
              type: array
              maxItems: 32
              items: { $ref: '#/components/schemas/RoutingImportRedirect' }
            rewrites:
              type: array
              maxItems: 32
              items: { $ref: '#/components/schemas/RoutingImportRewrite' }
            headers:
              type: object
              properties:
                noIndex: { const: true }
                noReferrer: { const: true }
                disableSensors: { const: true }
        changes:
          type: object
          required: [redirects, rewrites, headers]
          properties:
            redirects:
              type: [object, 'null']
              required: [revision, redirects]
              properties:
                revision: { type: integer, minimum: 0 }
                redirects:
                  type: array
                  maxItems: 32
                  items: { $ref: '#/components/schemas/RoutingImportRedirect' }
            rewrites:
              type: [object, 'null']
              required: [revision, rewrites]
              properties:
                revision: { type: integer, minimum: 0 }
                rewrites:
                  type: array
                  maxItems: 32
                  items: { $ref: '#/components/schemas/RoutingImportRewrite' }
            headers:
              type: [object, 'null']
              required: [revision, noIndex, noReferrer, disableSensors]
              properties:
                revision: { type: integer, minimum: 0 }
                noIndex: { type: boolean }
                noReferrer: { type: boolean }
                disableSensors: { type: boolean }
        issues:
          type: array
          maxItems: 64
          items:
            type: object
            required: [file, message]
            properties:
              file: { enum: [vercel.json, _redirects, _headers] }
              line: { type: integer, minimum: 1 }
              message: { type: string }
    HostingImportReview:
      type: object
      required: [source, repository, build, checks, domains]
      properties:
        source:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
        repository:
          type: [object, 'null']
          properties:
            provider: { type: string, enum: [github, gitlab, bitbucket] }
            url: { type: [string, 'null'], format: uri }
            branch: { type: [string, 'null'] }
        build:
          type: object
          properties:
            framework: { type: [string, 'null'] }
            rootDirectory: { type: [string, 'null'] }
            outputDirectory: { type: [string, 'null'] }
            nodeVersion: { type: [string, 'null'] }
            customBuildCommand: { type: boolean }
            customInstallCommand: { type: boolean }
            staticCandidate: { type: boolean, description: The reviewed settings indicate a possible static build path. Verify the output in preview. }
        checks:
          type: object
          properties:
            scheduledJobs: { type: integer, minimum: 0 }
            protectedDeployment: { type: boolean }
            usesMicrofrontends: { type: boolean }
            review:
              type: array
              items: { type: string }
        domains:
          type: object
          properties:
            available: { type: boolean }
            moreAvailable: { type: boolean }
            entries:
              type: array
              maxItems: 30
              items:
                type: object
                properties:
                  name: { type: string }
                  verified: { type: [boolean, 'null'] }
                  redirects: { type: boolean }
    RolloutHealthGuard:
      type: object
      additionalProperties: false
      required: [errorRateBps, minSamples]
      properties:
        errorRateBps: { type: integer, minimum: 100, maximum: 10000 }
        minSamples: { type: integer, minimum: 5, maximum: 50 }
    RolloutHealthEvidence:
      type: object
      additionalProperties: false
      required: [errorRateBps, minSamples, samples, serverErrors]
      properties:
        errorRateBps: { type: integer, minimum: 100, maximum: 10000 }
        minSamples: { type: integer, minimum: 5, maximum: 50 }
        samples: { type: integer, minimum: 5, maximum: 200 }
        serverErrors: { type: integer, minimum: 1, maximum: 200 }
    ProjectRolloutStages:
      type: array
      minItems: 2
      maxItems: 5
      uniqueItems: true
      description: Strictly increasing traffic shares in basis points. Use activate-release for final publication.
      items: { type: integer, minimum: 1, maximum: 9999 }
    ProjectCanary:
      type: [object, 'null']
      required: [baselineDeploymentId, candidateDeploymentId, baselineGeneration, trafficBasisPoints, updatedAt, revision, expiresAt, stages, healthGuard]
      properties:
        baselineDeploymentId: { type: string, format: uuid }
        candidateDeploymentId: { type: string, format: uuid }
        baselineGeneration: { type: integer, minimum: 0 }
        trafficBasisPoints: { type: integer, minimum: 1, maximum: 10000 }
        updatedAt: { type: integer, format: int64, description: Start of the current metrics window in Unix milliseconds }
        revision: { type: string, pattern: '^[a-f0-9]{32}$' }
        expiresAt: { type: [integer, 'null'], format: int64, description: Deadline in Unix milliseconds }
        stages:
          anyOf:
            - $ref: '#/components/schemas/ProjectRolloutStages'
            - type: 'null'
        healthGuard:
          anyOf:
            - $ref: '#/components/schemas/RolloutHealthGuard'
            - type: 'null'
    ProjectRolloutEvent:
      type: object
      required: [sequence, event, createdAt, baselineDeploymentId, candidateDeploymentId, baselineGeneration, trafficBasisPoints, expiresAt]
      properties:
        healthGuard: { $ref: '#/components/schemas/RolloutHealthGuard' }
        health:
          $ref: '#/components/schemas/RolloutHealthEvidence'
          description: Evidence present for an automatic stop caused by the health rule.
        sequence: { type: integer, format: int64, minimum: 1 }
        event: { type: string, enum: [started, updated, ended, expired] }
        createdAt: { type: integer, format: int64, description: Event time in Unix milliseconds. An expired event uses the deadline. }
        baselineDeploymentId: { type: string, format: uuid }
        candidateDeploymentId: { type: string, format: uuid }
        baselineGeneration: { type: integer, minimum: 0 }
        trafficBasisPoints: { type: integer, minimum: 1, maximum: 10000 }
        expiresAt: { type: [integer, 'null'], format: int64, description: Deadline in Unix milliseconds }
    RolloutSampleMetrics:
      type: [object, 'null']
      properties:
        releaseId: { type: string, format: uuid }
        samples: { type: integer, minimum: 0 }
        serverErrors: { type: integer, minimum: 0 }
        serverErrorRateBps: { type: [integer, 'null'], minimum: 0, maximum: 10000 }
        averageLatencyMs: { type: [integer, 'null'], minimum: 0 }
        p95LatencyMs: { type: [integer, 'null'], minimum: 0 }
    WorkspaceHostedRequestCapSettings:
      type: object
      required: [maxMonthlyRequests, revision]
      properties:
        maxMonthlyRequests: { type: [integer, 'null'], minimum: 1, maximum: 1000000 }
        revision: { type: integer, minimum: 0 }
    ReleaseApprovalPolicy:
      type: object
      required: [required, revision]
      properties:
        required: { type: boolean }
        revision: { type: integer, minimum: 0 }
    StaticReleaseCopyOptions:
      type: object
      properties:
        tag: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$' }
        operationId: { type: string, format: uuid, description: Reuse with the same source and tag to recover a retained copy after an interrupted request. }
    GitBranchLookup:
      type: object
      required: [repositoryUrl]
      properties:
        repositoryUrl: { type: string, format: uri }
        page: { type: integer, minimum: 1, maximum: 20, default: 1 }
    CiPreviewTokenStatus:
      type: object
      required: [expiresAt]
      properties:
        expiresAt: { type: [integer, 'null'], description: Unix milliseconds when the active token expires }
    InquiryReadTokenStatus:
      type: object
      required: [expiresAt, readsToday, dailyReadLimit]
      properties:
        expiresAt: { type: [integer, 'null'], description: Unix milliseconds when an active credential expires }
        readsToday: { type: integer, minimum: 0 }
        dailyReadLimit: { type: integer, const: 100 }
    ScheduledRecordsSnapshot:
      type: object
      required: [scheduleId, snapshotId]
      properties:
        scheduleId: { type: string, format: uuid }
        snapshotId: { type: string, pattern: '^[1-9][0-9]{0,15}$' }
    RecordsRecord:
      type: object
      additionalProperties: false
      required: [key, value, revision, updatedAt]
      properties:
        key: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
        value: { description: JSON value of at most 4096 serialized UTF-8 bytes }
        revision: { type: string, format: uuid }
        updatedAt: { type: integer, minimum: 0, maximum: 9007199254740991 }
    RecordsRecordResponse:
      type: object
      additionalProperties: false
      required: [record]
      properties:
        record: { $ref: '#/components/schemas/RecordsRecord' }
    RecordsRecordPage:
      type: object
      additionalProperties: false
      required: [records, next]
      properties:
        records:
          type: array
          maxItems: 25
          items: { $ref: '#/components/schemas/RecordsRecord' }
        next: { type: [string, 'null'], pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
    RecordsRestorePreview:
      type: object
      additionalProperties: false
      required: [name, recordCount, currentRecords, remainingRecords, remainingOperations, conflicts, canRestore, reason, previewToken]
      properties:
        name: { type: string, minLength: 2, maxLength: 64 }
        recordCount: { type: integer, minimum: 1, maximum: 200 }
        currentRecords: { type: integer, minimum: 0, maximum: 200 }
        remainingRecords: { type: integer, minimum: 0, maximum: 200 }
        remainingOperations: { type: integer, minimum: 0, maximum: 2000 }
        conflicts:
          type: array
          maxItems: 200
          items:
            type: object
            additionalProperties: false
            required: [collection, key]
            properties:
              collection: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
              key: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
        canRestore: { type: boolean }
        reason: { type: [string, 'null'], enum: [conflicts, capacity, quota, null] }
        previewToken: { type: [string, 'null'], pattern: '^[a-f0-9]{64}$', description: Opaque review binding; contains no public epoch, store generation or authorization credential. }
    ProjectRecordsLimits:
      type: object
      additionalProperties: false
      required: [recordLimit, operationsLimit, valueLimit]
      properties:
        recordLimit: { type: integer, const: 200 }
        operationsLimit: { type: integer, const: 2000 }
        valueLimit: { type: integer, const: 4096 }
    ProjectRecordsDatabase:
      type: object
      additionalProperties: false
      required: [name, createdAt, tokenExpiresAt, operations, records]
      properties:
        name: { type: string, minLength: 2, maxLength: 64 }
        createdAt: { type: integer, minimum: 0, maximum: 9007199254740991 }
        tokenExpiresAt: { type: [integer, 'null'], minimum: 0, maximum: 9007199254740991 }
        operations: { type: integer, minimum: 0, maximum: 9007199254740991, description: Current SQL UTC month's reserved runtime attempts; not provider usage or billing. }
        records: { type: integer, minimum: 0, maximum: 9007199254740991 }
    ProjectRecordsState:
      type: object
      additionalProperties: false
      required: [database, limits]
      properties:
        database:
          anyOf:
            - $ref: '#/components/schemas/ProjectRecordsDatabase'
            - type: 'null'
        limits: { $ref: '#/components/schemas/ProjectRecordsLimits' }
    ProjectRecordsCreated:
      type: object
      additionalProperties: false
      required: [database, limits]
      properties:
        database:
          type: object
          additionalProperties: false
          required: [name]
          properties:
            name: { type: string, minLength: 2, maxLength: 64 }
        limits: { $ref: '#/components/schemas/ProjectRecordsLimits' }
    ProjectRecordsCredential:
      type: object
      additionalProperties: false
      required: [token, expiresAt]
      properties:
        token: { type: string, pattern: '^sd_[a-f0-9-]{72}$' }
        expiresAt: { type: integer, minimum: 1, maximum: 9007199254740991 }
    RecordsExport:
      type: object
      additionalProperties: false
      required: [name, records]
      properties:
        name: { type: string, minLength: 2, maxLength: 64 }
        records:
          type: array
          maxItems: 200
          items:
            type: object
            additionalProperties: false
            required: [collection, key, value, revision, updatedAt]
            properties:
              collection: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
              key: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
              value: { description: JSON value up to 4 KiB }
              revision: { type: string, format: uuid }
              updatedAt: { type: integer, minimum: 0 }
      description: Owner or scheduled Records export. Empty stores export an empty records array; restore input separately requires at least one record. Authorization epochs, store generations and private credential information are not exposed.
    RecordsSnapshot:
      allOf:
        - $ref: '#/components/schemas/RecordsExport'
        - type: object
          properties:
            records: { type: array, minItems: 1 }
      description: A nonempty Records export accepted for restore after owner review. Preview tokens are bound internally to original authority and destination store lifecycle.
  requestBodies:
    ReleaseApprovalRevision:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [revision]
            properties:
              revision: { type: integer, minimum: 0 }
  responses:
    RecordsRecord:
      description: Current JSON record with its unchanged quoted revision ETag
      headers:
        ETag:
          schema: { type: string, pattern: '^"[a-f0-9-]{36}"$' }
        Cache-Control:
          schema: { type: string, const: 'no-store, no-transform' }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RecordsRecordResponse' }
    RecordsRestorePreview:
      description: Restore counts/conflicts and opaque previewToken when eligible; no records inserted or private authorization fields exposed
      content:
        application/json:
          schema: { $ref: '#/components/schemas/RecordsRestorePreview' }
    RecordsRestoreResult:
      description: Count of records atomically restored after current owner review
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required: [restored]
            properties:
              restored: { type: integer, minimum: 1, maximum: 200 }
    NativeServiceOperations:
      description: Private version-2 bounded page of native SQL/KV journal metadata and redacted quota receipt summaries; no provider is queried or native service state changed
      headers:
        Cache-Control:
          schema: { type: string, pattern: 'private.*no-store' }
        X-Stackr-Inspection-Units:
          schema: { type: integer, const: 1 }
          description: Fixed shared inspection reservation, not journal RPC count, provider usage or money.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/NativeServiceOperationsReport' }
    NativeRecoverySnapshot:
      description: Private native SQL/KV recovery metadata; no provider is queried and no native resource or usage state is changed
      headers:
        Cache-Control:
          schema: { type: string, pattern: 'private.*no-store' }
        X-Stackr-Inspection-Units:
          schema: { type: integer, const: 1 }
          description: Fixed shared inspection reservation, not provider usage or money.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/NativeRecoverySnapshot' }
    NativeRecoveryExport:
      description: Canonical unsigned private recovery export; grants no issuer, provider or execution authority
      headers:
        Cache-Control:
          schema: { type: string, const: 'private, no-store, no-transform' }
        Content-Disposition:
          schema: { type: string, pattern: '^attachment; filename="stackr-native-recovery-[a-f0-9-]{36}\.json"$' }
        X-Stackr-Inspection-Units:
          schema: { type: integer, const: 1 }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/NativeRecoveryExport' }
    NativeRecoveryAssessment:
      description: Advisory comparison with current or stale status; no recovery approval or mutation follows
      headers:
        Cache-Control:
          schema: { type: string, pattern: 'private.*no-store' }
        X-Stackr-Inspection-Units:
          schema: { type: integer, const: 1 }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/NativeRecoveryAssessment' }
    NativeRecoveryInspectionLimited:
      description: Shared inspection request/unit/slot capacity exhausted. Retry-After is a hint; daily exhaustion can last until SQL UTC rollover. Admitted work is nonrefundable.
      headers:
        Retry-After:
          schema: { type: string, const: '30' }
    WorkspaceHostedRequestCap:
      description: Current workspace request cap and metered request count
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/WorkspaceHostedRequestCapSettings'
              - type: object
                required: [requests, month, maxAllowedMonthlyRequests]
                properties:
                  requests: { type: integer, minimum: 0 }
                  month: { type: string, pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$' }
                  maxAllowedMonthlyRequests: { type: integer, const: 1000000 }
    ReleaseApprovalPolicy:
      description: Current approval policy
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ReleaseApprovalPolicy' }
    ReleaseApproval:
      description: Current policy and owner approval timestamp for the release
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ReleaseApprovalPolicy'
              - type: object
                required: [approvedAt]
                properties:
                  approvedAt: { type: [integer, 'null'], description: Unix milliseconds when approved }
    StaticReleaseCopyReceipt:
      description: Copy staged or recovered from a previous operation
      content:
        application/json:
          schema:
            type: object
            required: [deploymentId, copiedFrom, active]
            properties:
              deploymentId: { type: string, format: uuid }
              copiedFrom: { type: string, format: uuid }
              active: { const: false, description: A copy operation stages a release without publishing it. }
    GitBranchPage:
      description: Up to 25 branches and the next page if available
      content:
        application/json:
          schema:
            type: object
            required: [branches, nextPage]
            properties:
              branches:
                type: array
                maxItems: 25
                items:
                  type: object
                  required: [name, commit]
                  properties:
                    name: { type: string, maxLength: 100 }
                    commit: { type: string, pattern: '^[a-f0-9]{40}$' }
              nextPage: { type: [integer, 'null'], minimum: 2, maximum: 20 }
    TrafficOverageSettings:
      description: Workspace traffic overage settings and paid usage
      content:
        application/json:
          schema:
            type: object
            required: [available, enabled, priceMicros, acceptedPriceMicros, maxMonthlyMicros, maxAllowedMonthlyMicros, month, chargedMicros, paidRequests]
            properties:
              available: { type: boolean, description: Live prepaid wallet and traffic overage pricing are configured }
              enabled: { type: boolean, description: The workspace has active consent at the current price }
              priceMicros: { type: [integer, 'null'], minimum: 1, maximum: 100000, description: Current price per eligible request in USD micros }
              acceptedPriceMicros: { type: [integer, 'null'], minimum: 1, maximum: 100000, description: Price per request approved by the owner in USD micros }
              maxMonthlyMicros: { type: [integer, 'null'], minimum: 1, maximum: 100000000, description: Approved monthly spending cap in USD micros }
              maxAllowedMonthlyMicros: { type: integer, const: 100000000, description: Largest configurable spending cap in USD micros }
              month: { type: string, pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$', description: UTC billing month }
              chargedMicros: { type: integer, minimum: 0, maximum: 100000000, description: Traffic charges for the current UTC month in USD micros }
              paidRequests: { type: integer, minimum: 0, description: Paid traffic requests admitted in the current UTC month }
    ZogyAddress:
      description: Current owner address state. URL is present when the project is live and ingress is enabled.
      content:
        application/json:
          schema:
            type: object
            required: [available, routeReady, domain, hostname, label, changedAt, url]
            properties:
              available: { type: boolean, description: Address reservations are enabled }
              routeReady: { type: boolean, description: Address ingress is enabled }
              domain: { const: apps.zo.gy }
              hostname: { type: [string, 'null'] }
              label: { type: [string, 'null'] }
              changedAt: { type: [integer, 'null'], description: Unix time in milliseconds }
              url: { type: [string, 'null'], format: uri }
  securitySchemes:
    UsageBillingOperator:
      type: http
      scheme: bearer
      description: Separate STACKR_USAGE_BILLING_OPERATOR_TOKEN. Canonical HTTPS operator requests must omit Cookie and Origin headers; this credential grants no owner-session review authority.
    NativeRecoveryOperatorToken:
      type: http
      scheme: bearer
      description: Distinct STACKR_NATIVE_RECOVERY_OPERATOR_TOKEN of 43–128 random base64url characters. Send to the exact canonical HTTPS origin without Cookie or Origin headers. Existing service-usage/object-storage operator secrets do not grant this channel. Metadata/operation-record inspection, snapshot export and advisory comparison only; no hold release, usage correction, provider execution, approval, refund or billing authority.
    ServiceUsageOperatorToken:
      type: http
      scheme: bearer
      description: Separate STACKR_SERVICE_USAGE_OPERATOR_TOKEN, 43–128 base64url characters, used only for native service metadata usage/export audit. Send to the exact canonical
        HTTPS origin without Cookie or Origin headers. The existing object-storage token is not accepted. It grants no owner consent, provider action, billing or pricing authority.
    ObjectStorageOperatorToken:
      type: http
      scheme: bearer
      description: Separate STACKR_OBJECT_STORAGE_OPERATOR_TOKEN, 43–128 base64url characters. Send only from a server or terminal to the exact canonical HTTPS origin, without Cookie or Origin headers. Storage resource inspection, usage reporting and durable review receipts. Inspection admission/observation metadata and authenticated review receipts can be written. This credential grants no provider execution, recovery approval, cleanup retry, quota release or billing authority.
    CiPreviewToken:
      type: http
      scheme: bearer
      description: Project credential for server-to-server static ZIP staging only.
    InquiryReadToken:
      type: http
      scheme: bearer
      description: Separate credential issued from the Inquiries page.
    ProjectQueueToken:
      type: http
      scheme: bearer
      description: Worker credential issued from the Job queues dashboard. Project ownership, owner identity and account changes revoke it permanently; a new token must be issued after access is restored.
    ProjectQueueProducerToken:
      type: http
      scheme: bearer
      description: Enqueue-only credential issued from the Job queues dashboard. Project ownership, owner identity and account changes revoke it permanently; a new token must be issued after access is restored.
    ProjectEventProducerToken:
      type: http
      scheme: bearer
    ProjectEventConsumerToken:
      type: http
      scheme: bearer
    BuildEnvironmentToken:
      type: http
      scheme: bearer
      description: Thirty-day token issued from the selected project's Environment variables page.
    OwnerSession:
      type: apiKey
      in: cookie
      name: stack_session
      description: Stackr browser session. Owner actions require the canonical Stackr origin.
    ScheduleToken:
      type: http
      scheme: bearer
      description: Scoped key issued from the project Schedules page. Current original owner/identity/epoch/account policy and exact key expiry/revocation are checked during work and private reads. It can read the latest backup without a snapshot selector and explicitly run or reenable jobs; selected snapshots, backup history and credential controls require the owner session. Prepared migration 0101 revokes all legacy keys and future authority-epoch changes revoke replacements and pause automatic backup jobs; owners must authorize reenable with current credentials.
    ProjectLogToken:
      type: http
      scheme: bearer
      description: Read-only project log token issued from Observability. Export clients use the canonical HTTPS origin.
    ProjectAlertFeedToken:
      type: http
      scheme: bearer
      description: Read-only alert feed token issued from Alerts. Collectors use the canonical HTTPS origin.
    ProjectReleaseEventFeedToken:
      type: http
      scheme: bearer
      description: Read-only token issued from Release events. Send requests to the canonical HTTPS origin without browser cookies.
    SqlToken:
      type: http
      scheme: bearer
      description: Dedicated project database credential. Project ownership, owner identity and account changes revoke it permanently; a new token must be issued after access is restored.
    DatabaseToken:
      type: http
      scheme: bearer
      description: Project Records key issued by the current owner for runtime /api/data routes. It expires after 30 days and is revoked by ownership, identity or account epoch changes. Prepared migration 0101 revokes all legacy Records keys when applied, preserving data, backups and counters. Store lifecycle and exact current credential are checked during admission/read/write/final return. This key does not grant owner management, export or restore access.
    DeployToken:
      type: http
      scheme: bearer
  parameters:
    ObjectReviewRecordId:
      in: path
      name: recordId
      required: true
      schema: { type: string, format: uuid }
      description: Server-created review record identifier, distinct from an unsigned advisory packet.
    ObjectAttemptId:
      name: attemptId
      in: path
      required: true
      schema: { type: string, format: uuid }
    ReleaseWebhookId:
      name: webhookId
      in: path
      required: true
      schema: { type: string, format: uuid }
    QueueWebhookId:
      name: endpointId
      in: path
      required: true
      schema: { type: string, format: uuid }
    TrafficOverageOrigin:
      in: header
      name: Origin
      required: true
      description: Same Stackr origin as the request URL.
      schema: { type: string, format: uri }
    ScheduleJobId:
      in: path
      name: jobId
      required: true
      schema: { type: string, format: uuid }
    Collection:
      in: path
      name: collection
      required: true
      schema: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$' }
    ProjectId:
      in: path
      name: projectId
      required: true
      schema: { type: string, format: uuid }
