[Ahmad12developer]

Summary

Closes #325

Implements safe cancellation for long-running imports and exports in Trellis-frontend, ensuring immediate cessation of processing, automatic pre-write snapshot rollback, and role-based cancellation authorization without data corruption.

Acceptance Criteria Verification

• Cover normal, failure, retry, and authorization paths:
  • Normal: Full batch import execution and streaming export completion.
  • Failure: Schema validation errors and exhausted retry fetchers without false cancellation states.
  • Retry: Graceful, idempotent retry capability following cancellation, with immediate abort of backoff delays when cancelled during delay.
  • Authorization: Granular matrix enforcement on POST /api/operations/cancel and GET /api/operations (admins can cancel any operation; contributors can cancel operations owned by their wallet; viewers are denied with 403 Forbidden).
• Add automated tests or executable verification:
  • tests/__tests__/safe-cancellation.test.ts: 20 unit tests covering normal execution, failure paths, early cancellation, mid-write rollback, streaming helpers, and RBAC matrix.
  • lib/export/__tests__/streaming-export.test.ts: 23 unit tests verifying streaming export cancellation, retry backoff termination, and field permission handling.
• Document operational edge cases and recovery/rollback behavior:
  • Updated docs/import-pipeline.md detailing the snapshot rollback mechanism, cancellation endpoints, and compensation steps.
  • Updated lib/export/OPERATIONAL_GUIDE.md detailing stream cancellation, timeout handling, and memory safety.
• Preserve existing contracts or include a migration plan:
  • Preserved backward compatibility across runImportPipeline and streamingExport options (signal and onProgress are optional).
  • Preserved existing route contracts while adding /api/operations and /api/operations/cancel.

Key Changes

• Operation Registry (lib/cancellation/operation-registry.ts, lib/cancellation/index.ts):
  • In-memory thread-safe registry tracking active long-running operations with TTL cleanup, status queries (running, completed, cancelled, failed), and AbortController integration.
  • Role-based authorization: Admins can cancel any operation; wallet owners can cancel their own operations; viewers/unauthorized users are rejected with 403.
• Import Pipeline Safe Cancellation & Snapshot Rollback (lib/import/pipeline.ts, lib/import/stream.ts):
  • Checks abort signal before execution, during validation loops, and between persistent writes.
  • Creates pre-write snapshot via importStore.createSnapshot before executing persistent writes; on cancellation mid-write, automatically invokes importStore.restoreSnapshot to safely roll back all writes and prevent partial or corrupted state.
  • Emits descriptive rollbackGuidance and cancellation metadata.
• Streaming Export Cancellation (lib/export/streaming-export.ts):
  • Propagates cancellation signals to batch pagination and aborts fetch retry loops immediately without waiting through retry backoff delays.
• Operations & Cancellation API Routes (app/api/operations/route.ts, app/api/operations/cancel/route.ts):
  • GET /api/operations: Inspect active and past operations with role-based visibility.
  • POST /api/operations/cancel: Request cooperative cancellation with audit log.
• UI Integration (components/import/ImportProgressModal.tsx):
  • Added user-facing cancellation control with status feedback and confirmation.

Verification & Testing

npx jest tests/__tests__/safe-cancellation.test.ts lib/export/__tests__/streaming-export.test.ts --coverage=false
# Output:
# PASS tests/__tests__/safe-cancellation.test.ts (20/20 passed)
# PASS lib/export/__tests__/streaming-export.test.ts (23/23 passed)
# Test Suites: 2 passed, 2 total
# Tests:       43 passed, 43 total

[preshotta]

Merged after updating/checking against the live base branch and passing the required Malware guard. The earlier status comment was based on an older GitHub merge preview or a branch that did not need updating; it was not a finding that this contribution introduced malware.

Please fix and rerun the remaining non-security checks:

• ci
• playwright ()

[preshotta]

Merged as requested after the required Malware guard passed. Non-security checks are still failing; please fix and rerun these checks:

• ci
• playwright ()