test(#18): orchestrator behavioral tests (step sequencing, failure rollback, lock/session lifecycle) + output-stream fix

[Cadacious]

Implements #18 — behavioral orchestrator tests with the infra boundary mocked. 59 new tests; suite 1128 → 1187; build.ps1 BUILD OK.

Coverage before → after

Orchestrator	Before	After
Invoke-SEBBackup	0%	71%
Invoke-SEBRestore	0%	64%
Undo-SEBRestore	54%	62%

What's tested (the high-value part is failure rollback, not the happy path)

• Happy paths (full + incremental backup; restore) assert the result object AND the step order via Should -Invoke.
• Failure injection — one seam fails at a time, asserting correct abort + cleanup: preflight/lock-held/VSS/compress/transfer/manifest/integrity for backup; chain-invalid/safety-backup-fail/verify-fail/deploy-fail/stop-fail for restore; the Undo-SEBRestore takes no lock and leaks its session #9 session-ownership guard + rollback-rename for undo. Every path asserts the lock is released (and an owned session torn down) in finally.
• -WhatIf performs no mutating seam calls.
• Non-vacuousness mutation-verified: removing the safety-backup abort, the verify abort, the finally lock-release, or the output fix each makes a test fail.

Source fix (behavior-preserving)

Found a real output-stream-hygiene defect: several data-path seams (Compress-SEBArchive, Copy-SEBThrottled, side-effect-only remote blocks) had uncaptured [PSCustomObject] results, so $result = Invoke-SEBBackup ... actually returned an array @(compressObj, …, $result) rather than the documented single PSCustomObject — it only "worked" because the leaked objects lack a .Success member. Fixed with | Out-Null (5 sites in backup, 6 in restore) + comments; no logic change. Pinned by @($r).Count | Should -Be 1 + Should -BeOfType PSCustomObject.

No Private seam extraction was needed — every branch was reachable by mocking existing SEB functions. Contract tests stay 496/496 green.

Closes #18.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Backup and restore commands now return cleaner, more predictable output by suppressing extra internal results.
  • Improved reliability across backup and restore flows, including better handling of cleanup, transfer, and validation steps.
  • Restores now handle undo and rollback scenarios more consistently, with better recovery when temporary files or directories are involved.
• Tests
  • Expanded automated coverage for backup, restore, and undo flows, including success paths, failure handling, and cleanup behavior.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Backup and restore now discard helper-call output so the cmdlets emit only intended results. New Pester suites cover backup, restore, and undo success, failure, option, and rollback paths.

Changes

Orchestrator output suppression and test coverage

Layer / File(s)	Summary
Backup output suppression Modules/BackupEngine/Public/Invoke-SEBBackup.ps1	Invoke-SEBBackup pipes prune, compression, archive transfer, NAS copy, and final cleanup results to Out-Null.
Backup success-path tests Tests/BackupEngine/Invoke-SEBBackup.Tests.ps1	The backup suite adds temp-root scaffolding plus FULL and INCREMENTAL success-path assertions for object shape, stage order, manifest wiring, and cleanup.
Backup failure and gating tests Tests/BackupEngine/Invoke-SEBBackup.Tests.ps1	The backup suite adds failure-injection coverage and checks notification, lock/session, load-check, VRage, and WhatIf behavior.
Restore output suppression Modules/RestoreEngine/Public/Invoke-SEBRestore.ps1	Invoke-SEBRestore pipes temp-dir reset, archive transfer/extract, deleted-file cleanup, temp archive cleanup, and final restore-temp cleanup results to Out-Null.
Restore success-path tests Tests/RestoreEngine/Invoke-SEBRestore.Tests.ps1	The restore suite adds temp-manifest scaffolding plus success-path assertions, safety-backup re-entrancy, restore notifications, and structured failure cases.
Restore prompts and options Tests/RestoreEngine/Invoke-SEBRestore.Tests.ps1	The restore suite covers -SkipSafetyBackup, degraded start warnings, notification gating, declined prompts, and -Force bypass behavior.
Undo shared mocks and failure cases Tests/RestoreEngine/Undo-SEBRestore.Tests.ps1	The undo suite centralizes shared mocks, then covers rename failure cleanup, lock acquisition failure, no-prerestore-directory failure, stop-server failure, cached-session handling, notifications, and post-rename start-server failure.
Undo rollback verification Tests/RestoreEngine/Undo-SEBRestore.Tests.ps1	The undo suite runs the extracted rollback script block against temp directories to verify rename-back success, rename-back failure recovery, and the no-current-world-directory case.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• SandboxServers/SEBackup#1: Also touches Invoke-SEBBackup and Invoke-SEBRestore orchestration behavior in the same cmdlet surface.
• SandboxServers/SEBackup#58: Also changes remote-command/session handling used by the backup and restore flows in this PR.

Poem

I hopped through backups, soft and neat,
and tucked stray output under my feet.
Restore trails gleam, undo winds back the night,
with tests like clover guarding each bite.
🐇 The burrow hums: clean streams, all bright.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: orchestrator behavioral tests plus output-stream cleanup.
Linked Issues check	✅ Passed	The PR adds happy and failure-path tests for the backup and restore orchestrators with mocked infra boundaries.
Out of Scope Changes check	✅ Passed	The added restore and undo tests plus the output-stream fix remain directly tied to the orchestrator behavior work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch test/18-orchestrator-seams

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Adds high-value behavioral coverage for the backup/restore orchestrators (including failure rollback and lifecycle cleanup) and fixes output-stream hygiene so orchestrators reliably return a single result object as documented.

Changes:

• Introduces comprehensive Pester behavioral tests for Invoke-SEBBackup and Invoke-SEBRestore, asserting step sequencing and failure-path cleanup/rollback behavior.
• Expands Undo-SEBRestore lifecycle tests to cover additional abort paths and notification behavior.
• Applies | Out-Null at side-effect-only seams (and Copy-SEBThrottled / Compress-SEBArchive results) to prevent unintended objects from leaking into orchestrator output streams.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Tests/RestoreEngine/Undo-SEBRestore.Tests.ps1	Adds new undo failure-path and notification/lifecycle assertions.
Tests/RestoreEngine/Invoke-SEBRestore.Tests.ps1	New restore orchestrator behavioral suite (happy path + failure injection + contracts).
Tests/BackupEngine/Invoke-SEBBackup.Tests.ps1	New backup orchestrator behavioral suite, including output-stream contract pinning.
Modules/RestoreEngine/Public/Invoke-SEBRestore.ps1	Discards unused seam outputs to preserve single-object .OUTPUTS contract.
Modules/BackupEngine/Public/Invoke-SEBBackup.ps1	Discards unused seam outputs to prevent output-stream leakage into caller results.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.