ai-contract-platform/project-docs/V2-phase3-ai-platform-trace-policy-config-2026-07-03.md

# V2 Phase 3 AI Platform Trace Policy Configuration

Date: 2026-07-03

## Status

Local implementation completed.

This slice makes AI Trace retention, redaction, and archive behavior configurable without changing the production worker enablement decision.

Current operational decision:

- Smoke can keep `YUQEI_WORKER_TRACE_GOVERNANCE_ENABLED=true`.
- Production keeps Trace governance disabled for now.
- The 24-hour smoke observation remains a pre-production checklist item, not a blocker for current development.

## Schema

New AI Platform migration:

```text
20260703_0021_add_trace_governance_policies.py
```

New table:

```text
trace_governance_policies
```

The first slice stores one policy per tenant:

- `tenant_id`
- `enabled`
- `default_retention_days`
- `default_redaction_policy`
- `require_redaction`
- `auto_archive`
- `changed_by`
- `change_note`
- `updated_at`

Default policy is intentionally conservative:

- `enabled=false`
- `default_retention_days=90`
- `default_redaction_policy=default`
- `require_redaction=false`
- `auto_archive=true`

Because the default is disabled, existing production/smoke behavior does not change until an administrator enables the policy for a tenant.

## Runtime API

New endpoints:

```text
GET /api/v1/runtime/trace-governance/policy
PUT /api/v1/runtime/trace-governance/policy
```

The endpoints use the existing tenant context:

- With `X-Tenant-Id`, the tenant-specific policy is read/written.
- Without `X-Tenant-Id`, the `default` tenant policy is used.

Contract Web local proxy:

```text
GET /api/ai-platform/runtime/trace-governance/policy
PUT /api/ai-platform/runtime/trace-governance/policy
```

## Worker Behavior

The policy is applied in two places:

1. When a new AI run audit is created.
2. At the start of each Trace governance worker run, for a bounded batch of existing unconfigured traces.

Rules:

- Existing explicit `retention_until` is not overwritten.
- Existing non-default redaction policy is not overwritten.
- Existing `redaction_status=redacted` is not reverted.
- If policy is disabled, existing explicit `redaction_status=pending|required` and explicit expired `retention_until` behavior remains unchanged.
- If policy is enabled and `require_redaction=true`, unconfigured traces are marked `redaction_status=required`.
- If policy is enabled and `auto_archive=false`, the worker does not archive traces only because of retention due dates.

## Admin UI

`/admin/ai-runtime` now includes a Trace policy form in the Trace governance panel.

Controls:

- Enabled
- Retention days
- Redaction policy
- Require redaction
- Auto archive
- Change note

The existing Trace governance status panel still shows heartbeat, last-30-minute execution count, recent run count, failed count, latest runs, and manual run action.

## Validation

Local validation passed:

```powershell
python -m py_compile `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\repository.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\persistence\audit.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\persistence\worker_runtime.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\api\system.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\schema_check.py `
  yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api\models.py

python -m pytest yuqei-ai-platform\services\ai-platform-api\tests -q
python -m pytest yuqei-ai-platform\services\worker\tests -q
npm run web:typecheck
```

Results:

- AI Platform API tests: 61 passed.
- Worker tests: 6 passed.
- Contract Web typecheck: passed.

Targeted behavior verified:

- Policy GET returns a tenant-scoped disabled default.
- Policy PUT persists tenant-scoped retention/redaction/archive settings.
- New traces inherit enabled policy defaults.
- Existing unconfigured SQLAlchemy traces are picked up by the next governance run.
- `answer_only` and `prompt_only` redaction semantics remain intact.
- `schema-check` now verifies the policy table and policy columns.

## Remaining Items

- Keep production Trace governance disabled until the pre-production observation gate is completed.

## Smoke Verification

Remote smoke verification completed on `192.168.3.90`.

Deployment artifacts:

- Full smoke deploy: `project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-03T17-18-54`
- Web proxy environment fix redeploy: `project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-07-03T17-30-17`

Schema:

```text
AI Platform Alembic version: 20260703_0021
GET http://192.168.3.90:18101/api/v1/runtime/schema-check -> ok
```

Schema-check highlights:

- Database: `yuqei_ai`
- Alembic actual/expected: `20260703_0021`
- Core tables checked: `16`
- Tenant column tables checked: `8`
- Trace governance columns checked: `11`
- PostgreSQL extensions: `pg_trgm,vector`
- pgvector schema: `ok`

Policy API:

```text
GET /api/v1/runtime/trace-governance/policy
PUT /api/v1/runtime/trace-governance/policy
POST /api/v1/runtime/trace-governance/run-once
```

Verified tenant: `trace-policy-smoke-20260703`

Applied smoke policy:

```json
{
  "enabled": true,
  "default_retention_days": 0,
  "default_redaction_policy": "answer_only",
  "require_redaction": true,
  "auto_archive": true
}
```

Verified real Trace:

- Created smoke AI Trace: `run-c2f71bb35a9f`.
- New Trace inherited policy fields: `redaction_status=required`, `redaction_policy=answer_only`, `retention_until` populated.
- Manual governance run: `worker-run-55d177effe2b`.
- Governance stats: `scanned=1`, `redacted=1`, `archived=1`, `failed=0`.
- Detail after governance: `answer=[REDACTED]`, `quality_summary=[REDACTED]`, `archive_status=archived`.

Worker:

- Smoke `.env.smoke`: `YUQEI_WORKER_TRACE_GOVERNANCE_ENABLED=true`.
- Worker container settings verified: `trace_governance_enabled=True`, interval `300`, batch limit `100`.
- Recent `worker_run_executions` show scheduled `trace-governance-worker` runs with `status=succeeded`.

Admin UI:

- `GET http://192.168.3.90:13000/admin/ai-runtime`: HTTP 200.
- Browser-rendered page contains Trace governance panel, Trace policy form, retention days input, and manual run button.
- Screenshot artifact: `project-docs/qa-artifacts/v2-trace-policy-smoke-verification/ai-runtime-remote-trace-policy.png`.
- Layout check at 1440px: no horizontal overflow.

Implementation note:

- Contract Web needed `AI_PLATFORM_API_BASE_URL=http://ai-platform-api:8101` in Docker compose so server-side Next API proxies can reach AI Platform from inside the container.

## Remaining Items

- Keep production Trace governance disabled until the pre-production observation gate is completed.