TenantAtlas/specs/093-scope-001-workspace-id-isolation/contracts/cli.md

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.