# Premium DM Precheck User-Facing Initialization Errors

## Analysis

| Area | Current behavior | Target behavior | Verification |
| --- | --- | --- | --- |
| ng-agent DM precheck | `PrecheckDMJob` returns errors directly from `buildPrecheckConfigs` or `checker.RunCheckOnConfigs`, so gateway responses can expose wrapped error formatting. Checker initialization errors contain `fail to initialize checker` and no stable `Message` / `Workaround` fields. | Convert DM precheck config/checker errors to clean `InvalidArgument` status messages in ng-agent. Do not parse serverless-specific `Message:` / `Workaround:` fields. | Unit tests for clean status conversion and helper classification. |
| Premium DM item executor | Agent errors mark item stage `failed` with generic `err_msg`, and API hides details as internal error. | Persist user-facing init failures as `stage=finished` with checker-shaped failed `results`, so existing API formatter exposes `reason`. | Unit tests against `doPremiumPrecheckDMJob` using an HTTP test server that mimics ng-agent error responses. |
| Remaining items | After one shared initialization failure, later items would otherwise repeat the same agent RPC. | Skip subsequent RPCs and persist synthetic failed checker results with the same root cause. | Unit tests for `RunPrecheck` orchestration and final failed status via result aggregation. |

## Execution Steps

1. Add Premium DM precheck error helpers under `dataflow-service-ng/app/models/premium_dm`.
   - Extract clean ng-agent error messages from `agent.ErrorResponse` or plain errors.
   - Treat only messages that start with `fail to initialize checker` / `precheck execution failed` as user-facing.
   - Build `entity.PremiumResults` using `checker.StateFailure`.

2. Update ng-agent DM precheck error conversion.
   - Convert `buildPrecheckConfigs` and `checker.RunCheckOnConfigs` failures to `codes.InvalidArgument`.
   - Preserve clean `err.Error()` as the gRPC status message so the HTTP gateway response has no stack/wrapper text.

3. Update Premium DM precheck execution.
   - Extend `PrecheckItemRunner` to return a user-facing init failure reason.
   - In `RunPrecheck`, cache the first user-facing init failure and synthesize remaining item results without extra agent calls.
   - In `doPremiumPrecheckDMJob`, persist user-facing agent errors as finished checker results.

4. Verify.
   - Run `go test ./agent/grpc -run 'Test(BuildPrecheckConfigs|PrecheckDMJobClientError)'` in `dataflow-agent-ng`.
   - Run `go test ./app/models/premium_dm ./app/controllers/premium_dm` in `dataflow-service-ng`.
   - Run `make build-dataflow-darwin` in `dataflow-service-ng`.

## Risks

- Transport errors, timeouts, and agent infrastructure errors must remain internal failures.
- The fix depends on ng-agent’s current checker error wording; tests pin the clean prefix classification boundary.