KArtSell.Aegis/docs/CURRENT/PHASE-1_REQUEUE_READINESS.md

Phase 1 Shadow Run Requeue Readiness

Traceability

• WBS: PHASE-1-SHADOW-RUN
• Slice: requeue readiness and approval package
• Source: docs/CURRENT/WBS_EXECUTION_PROCEDURES.md, docs/CURRENT/PHASE-1_SHADOW_RUN_STATUS_CORRECTION.md, docs/CURRENT/AEG-X-004_DBUP_EVIDENCE.md, src/KArtSell.Host/Features/ShadowRun/API_CONTRACT.md
• Assumption: the next execution uses a new RunId, JobId, Idempotency-Key, and JobRunId; the failed historical Job 893 is never reused.
• Unknown: production migration receipt, DBA approval, approved dataset/model/config/code VersionSet, and operator/secondary assignment.
• Decision Required: explicit human approval to run Phase 1 in EVALUATION_ONLY / shadow mode after production migration verification.

Current evidence boundary

• 0032_shadow_run_queued_status_contract.sql is append-only and accepts the existing application Queued state.
• Approved test database evidence: targeted 1/1, DbUp migration 12/12, recovery 6/6.
• Job 893 was never started; no historical run may be resumed or mutated.
• Automatic order, KIS submission, model promotion, rollback automation, and threshold mutation remain disabled.

Unsafe legacy script

scripts/EXECUTE_PHASE_1_NOW.ps1 is not an approved execution path and must not be run. Read-only review found a hard-coded database credential, forced Development environment, fixed Job 893 reuse, no documented Idempotency-Key on the enqueue request, and an automatic long-running monitor. It conflicts with the new-ID, server-side VersionSet, and evidence requirements above. Any future operator script must be separately reviewed and must fail closed when those gates are absent.

Preflight gates

The operator must preserve command output and timestamps for every gate. A failed gate stops the procedure.

1. Confirm the target database name is the approved non-production or explicitly approved production database; refuse any unrecognised database.
2. Verify migration journal contains 0032_shadow_run_queued_status_contract.sql and the check_status constraint includes Queued.
3. Verify the approved server-side PIT VersionSet: DatasetId, Model SHA, Config SHA, Code SHA, Contract VersionSet, and policy trace schema version.
4. Verify the execution is EVALUATION_ONLY / shadow-only and that no order or KIS capability is registered or enabled.
5. Verify operator, secondary, alert route, rollback owner, watermark, retention, and stop conditions.
6. Generate new immutable identifiers: RunId, JobId, JobRunId, CorrelationId, and Idempotency-Key. Do not reuse Job 893.
7. Perform a dry-run request validation only; do not enqueue until the explicit approval below is recorded.

Approval record (required before enqueue)

Approval ID:
Approver / role:
Operator / secondary:
Target environment and database:
Migration receipt:
DatasetId / Model SHA / Config SHA / Code SHA:
Contract VersionSet / policy trace schema version:
New RunId / JobId / JobRunId / CorrelationId:
Stop conditions acknowledged:
Order/KIS capability confirmed OFF:
Approval timestamp (UTC):

Enqueue and observation boundary

After approval, use the documented POST /api/shadow-runs contract with the new Idempotency-Key and preserve the HTTP response. Poll only the new RunId. Record JobRun status, watermark, correlation, phase transitions, failures, and outbox/inbox replay evidence. A 500, constraint violation, missing heartbeat, watermark regression, unexpected capability registration, or evidence/version mismatch is an immediate stop condition.

Rollback / stop

Rollback means stop observation and preserve evidence; it does not delete or update Evidence, Decision, or Audit records. Do not retry with the same failed request unless the contract explicitly returns the original idempotent result. Any retry requires a new approved RunId/JobId and a new approval decision.

Completion rule

This readiness document does not claim Phase 1 is running or complete. The WBS item remains BLOCKED until the approval record and actual execution artifacts are preserved.