273 lines
9.1 KiB
YAML
273 lines
9.1 KiB
YAML
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 |