# CLI Contract — 093 Workspace ID Backfill

This feature adds an operator-only Artisan command to backfill missing `workspace_id` on tenant-owned tables.

## Command

- Name (proposed): `tenantpilot:backfill-workspace-ids`

## Flags / Options (proposed)

- `--dry-run` (default: false)
  - Prints counts per table and exits without writing.
- `--table=<name>` (optional)
  - Restrict execution to a single table.
- `--batch-size=<n>` (default: 5_000)
  - Batch size for updates (where chunking is used).
- `--resume-from=<cursor>` (optional)
  - Resume from a saved cursor/checkpoint (implementation-defined).
- `--max-rows=<n>` (optional)
  - Safety valve for partial runs.

## Safety + Observability

Execution strategy (queued):

- The command is a start surface only: authorize → acquire lock → create/reuse `OperationRun` → dispatch queued jobs → print a “View run” pointer.
- The backfill mutations MUST execute inside queued jobs (batch/table scoped) to support large datasets.

Safety + observability requirements:

- Must acquire a lock (cache/DB-backed lock) to prevent concurrent runs.
- Must create/reuse an `OperationRun` for visibility and progress tracking.
- Must write an `AuditLog` entry for start and end (outcome, counts, duration).
- Must abort and report when a tenant→workspace mapping cannot be resolved.

## Output

- Printed “Run started” summary:
  - `OperationRun` identifier (or URL/route reference when available)
  - jobs dispatched count
  - selected tables / scope

- Per-table totals:
  - scanned rows
  - rows missing `workspace_id`
  - rows updated
- Final summary + recommended validation SQL.