openapi: 3.1.0
info:
  title: Compare Job Legacy Drift Cleanup Internal Contract
  version: 0.1.0
  summary: Internal logical contract for the unchanged baseline compare start and execution path after legacy drift deletion
  description: |
    This contract is an internal planning artifact for Spec 205. No new HTTP
    controllers or routes are introduced. The paths below identify logical
    service, job, and guard boundaries that must remain true after the dead
    pre-strategy drift path is removed from CompareBaselineToTenantJob.
x-logical-artifact: true
x-compare-job-cleanup-consumers:
  - surface: baseline.compare.start
    sourceFiles:
      - apps/platform/app/Services/Baselines/BaselineCompareService.php
      - apps/platform/tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php
    mustRemainTrue:
      - compare_start_remains_enqueue_only
      - deterministic_strategy_selection_recorded_in_run_context
      - no_legacy_compare_fallback_at_start
  - surface: baseline.compare.execution
    sourceFiles:
      - apps/platform/app/Jobs/CompareBaselineToTenantJob.php
      - apps/platform/app/Support/Baselines/Compare/CompareStrategyRegistry.php
      - apps/platform/app/Support/Baselines/Compare/IntuneCompareStrategy.php
    mustConsume:
      - supported_strategy_selection
      - strategy_compare_result
      - normalized_strategy_subject_results
      - no_legacy_compute_drift_fallback
  - surface: baseline.compare.findings
    sourceFiles:
      - apps/platform/app/Jobs/CompareBaselineToTenantJob.php
    mustRemainTrue:
      - finding_lifecycle_unchanged
      - summary_and_gap_counts_derived_from_strategy_results
      - warning_outcomes_unchanged
      - reason_translation_unchanged
      - operation_run_completion_semantics_unchanged
  - surface: baseline.compare.guard
    sourceFiles:
      - apps/platform/tests/Feature/Guards/Spec116OneEngineGuardTest.php
      - apps/platform/tests/Feature/Guards/Spec118NoLegacyBaselineDriftGuardTest.php
    mustEnforce:
      - removed_legacy_methods_stay_absent
      - orchestration_file_has_one_compare_engine
  - surface: baseline.compare.run-guards
    sourceFiles:
      - apps/platform/tests/Feature/Guards/OperationLifecycleOpsUxGuardTest.php
      - apps/platform/tests/Feature/Operations/BaselineOperationRunGuardTest.php
      - apps/platform/tests/Feature/OpsUx/OperationSummaryKeysSpecTest.php
      - apps/platform/tests/Feature/OpsUx/SummaryCountsWhitelistTest.php
    mustEnforce:
      - baseline_compare_run_lifecycle_semantics_unchanged
      - summary_count_keys_remain_whitelisted
      - compare_run_context_updates_remain_valid
paths:
  /internal/tenants/{tenant}/baseline-profiles/{profile}/compare:
    post:
      summary: Start baseline compare using the existing strategy-selected flow only
      operationId: startBaselineCompareWithoutLegacyFallback
      parameters:
        - name: tenant
          in: path
          required: true
          schema:
            type: integer
        - name: profile
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompareLaunchRequest'
      responses:
        '202':
          description: Compare accepted and queued with the strategy-owned execution path only
          content:
            application/vnd.tenantpilot.baseline-compare-run+json:
              schema:
                $ref: '#/components/schemas/CompareLaunchEnvelope'
        '422':
          description: Existing unsupported or mixed-scope preconditions prevented compare from starting
        '403':
          description: Actor is in scope but lacks compare-start capability
        '404':
          description: Tenant or baseline profile is outside actor scope
  /internal/operation-runs/{run}/baseline-compare/execute:
    post:
      summary: Execute baseline compare through strategy selection and strategy compare only
      operationId: executeBaselineCompareJobWithoutLegacyFallback
      parameters:
        - name: run
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Existing compare run completed through the strategy-owned path with no legacy drift fallback
          content:
            application/vnd.tenantpilot.baseline-compare-execution+json:
              schema:
                $ref: '#/components/schemas/CompareExecutionEnvelope'
        '409':
          description: Existing snapshot, coverage, or strategy preconditions blocked execution
  /internal/guards/baseline-compare/no-legacy-drift:
    get:
      summary: Static invariant proving the orchestration file no longer retains the pre-strategy drift implementation
      operationId: assertNoLegacyBaselineCompareJobPath
      responses:
        '200':
          description: Guard passes because the removed legacy methods are absent from the compare job
          content:
            application/vnd.tenantpilot.compare-job-guard+json:
              schema:
                $ref: '#/components/schemas/LegacyDriftGuardResult'
components:
  schemas:
    CompareLaunchRequest:
      type: object
      additionalProperties: false
      required:
        - baseline_snapshot_id
        - effective_scope
      properties:
        baseline_snapshot_id:
          type: integer
        effective_scope:
          type: object
          additionalProperties: true
        origin:
          type: string
          enum:
            - tenant_profile
            - compare_matrix
            - other_existing_surface
    SupportedStrategySelection:
      type: object
      additionalProperties: false
      required:
        - selection_state
        - strategy_key
        - operator_reason
      properties:
        selection_state:
          type: string
          enum:
            - supported
        strategy_key:
          type: string
          example: intune_policy
        operator_reason:
          type: string
        diagnostics:
          type: object
          additionalProperties: true
    CompareLaunchEnvelope:
      type: object
      additionalProperties: false
      required:
        - run_id
        - operation_type
        - execution_mode
        - selected_strategy
        - legacy_drift_path_present
      properties:
        run_id:
          type: integer
        operation_type:
          type: string
          enum:
            - baseline_compare
        execution_mode:
          type: string
          enum:
            - queued
        selected_strategy:
          $ref: '#/components/schemas/SupportedStrategySelection'
        legacy_drift_path_present:
          type: boolean
          const: false
    CompareExecutionEnvelope:
      type: object
      additionalProperties: false
      required:
        - run_id
        - compare_source
        - selected_strategy_key
        - no_legacy_compute_drift
        - persisted_truths
      properties:
        run_id:
          type: integer
        compare_source:
          type: string
          enum:
            - strategy_only
        selected_strategy_key:
          type: string
          example: intune_policy
        no_legacy_compute_drift:
          type: boolean
          const: true
        persisted_truths:
          type: array
          items:
            type: string
          example:
            - operation_runs
            - findings
            - baseline_compare.context
        outputs_preserved:
          type: object
          additionalProperties: false
          properties:
            finding_lifecycle:
              type: boolean
              const: true
            summary_counts:
              type: boolean
              const: true
            gap_handling:
              type: boolean
              const: true
            warning_outcomes:
              type: boolean
              const: true
            reason_translation:
              type: boolean
              const: true
            run_completion:
              type: boolean
              const: true
    LegacyDriftGuardResult:
      type: object
      additionalProperties: false
      required:
        - status
        - compare_job_path
        - forbidden_method_names
      properties:
        status:
          type: string
          enum:
            - pass
        compare_job_path:
          type: string
          example: apps/platform/app/Jobs/CompareBaselineToTenantJob.php
        forbidden_method_names:
          type: array
          items:
            type: string
          example:
            - computeDrift
            - effectiveBaselineHash
            - resolveBaselinePolicyVersionId
            - selectSummaryKind
            - buildDriftEvidenceContract
            - buildRoleDefinitionEvidencePayload
            - resolveRoleDefinitionVersion
            - fallbackRoleDefinitionNormalized
            - roleDefinitionChangedKeys
            - roleDefinitionPermissionKeys
            - resolveRoleDefinitionDiff
            - severityForRoleDefinitionDiff
        invariant:
          type: string
          example: compare orchestration retains one live strategy-driven execution path