Selected-file backup and recovery workflow

Use this with pc-backup-recovery, the communication guide and the executing toolkit's current storage and workflow API documents. These helpers create bounded selected-file recovery artifacts; they do not promise a full-system image, application-consistent database snapshot, preserved ACLs or encrypted storage. Do not operate on real data during development tests.

1. Establish what must be recoverable

Explain the purpose in chat: a copy is useful only when its contents and restoration method match the owner's need. Record the actual backup/recovery job; owner-selected roots and file selection; exclusions; resource limits; retention; required or optional recovery; exact destination; guided or automatic control; now or scheduled timing; and checkpoints. Do not infer a whole user profile, other projects, mounted drives or a cloud account from a request to “back up important things.”

Use the current engine's authorize_scope gate to bind the actual owner's selected scope before assessment. Creating a session, changing settings or recording a confirmation fact does not by itself authenticate consent. Preserve immutable session/backend/mode identity; do not promote fictional evidence into a real run.

Start with approved metadata. Names and sizes may themselves be private. Before hashing, planning a content-bound backup, or archiving, obtain actual consent for bounded reads of the selected ordinary files. Metadata permission is insufficient. Known or suspected credential/password stores, authentication files, keys/tokens, private certificates, browser profiles/history/cookies/caches and saved chat/session data are excluded without opening them. Do not read a secret to determine whether it is a secret, hash it as a workaround, or copy it “just in case.” Resolve an ambiguous source by asking the owner to exclude or classify it, without requiring disclosure of its contents.

Unique nonsecret files can still be sensitive. Explain the intended destination's privacy and the consequence of inclusion or exclusion. Show the exact selection and exclusions before any backup. A readable file is not automatically suitable for copying, and a broad model-choice instruction is not a selection or content-read authorization.

Present a useful choice with benefits, drawbacks, costs and a recommendation:

For selected unique or sensitive nonsecret data, make the backup choice explicit. Explain whether backup is required for the proposed change or optional. An optional refusal can be recorded with its limits; it never becomes deletion approval. If verified recovery is a required prerequisite, hold the change until that condition is satisfied rather than converting it to optional under automatic mode.

2. Confirm capabilities, roles and source quietness

Read docs/STORAGE_BACKUP_API.md for exact current StorageService signatures and the workflow engine API for state and approval gates. Use the actual platform's safe filesystem adapter. The service's output root must be an existing positively owned child of the script-derived toolkit work/, as required by its API. No command, flag, external-destination support or native guarantee should be invented.

The constructor is StorageService(output_root=..., quiet_workspace=True, protected_roots=...). Supply actual known protected/custom-profile locations through protected_roots without scanning or opening them; name/location rules cannot prove all other files are nonsecret. Metadata assessment accepts 1–32 nonoverlapping directory roots with 10,000-entry and depth-48 caps, without a logical-byte content cap. Content hashing/backup separately allows 16 MiB per selected ordinary file and 48 MiB selected content payload per phase; archive output is bounded to 64 MiB. These payload caps are not an exact whole-operation I/O estimate because verification rereads the bounded data. Supported limits narrow caps, not enlarge them. A larger or unsupported content selection is an honest hold. Offer a smaller actual selection or a separately supported owner-managed recovery option; do not claim a generic large-backup executor, automatic chunking or an improvised copy is available. Current hardlinks/repeated identities and nonordinary entries are refused, not supported recovery targets.

Use one coordinator for canonical state, artifacts and every mutation. A matching platform/storage investigator checks source limits and safe reads; a verifier checks the recovery result. For each concrete backup or restoration/change plan, two distinct independent adversarial reviewers examine the same immutable plan/evidence: compatibility/data/recovery and evidence/security/scope. They return initial results independently. Without independent review, continue authorized read-only preparation and hold changes; never claim two self-reviews are independent.

Check source identity, ordinary-file status, ownership, actual adapter capabilities, resource/capacity limits and quiet owner-controlled workspace. Do not follow links, cross a selected-root boundary or repair ACLs to obtain a read. The helper operates with the caller's OS permissions and is not a sandbox against concurrent privileged or same-user tampering. A missing capability, lock, changed source or unreadable entry is an explicit hold or visible exclusion consistent with the plan, never an invitation to a weaker copy command.

Ask the owner to save and close an application only when necessary for the intended recovery and already authorized; do not force closure. Ordinary-file hashes do not prove an active database or multi-file application state is consistent. If the helper cannot provide the required application-level recovery, explain the gap and hold that promise.

3. Review exact contents, exclusions and destination

Use the metadata inventory and actual selected files to prepare plan_backup(inventory=..., selected=..., destination=..., content_read_authorized=True, required_recovery=..., exclusions=...). selected contains exact ordinary-file inventory keys; exclusions maps exact skipped keys to human-readable reasons. content_read_authorized=True records already-established bounded permission; it does not authenticate consent. Set required_recovery from the actual recovery decision, never to suppress a refusal. Explain:

• which exact files and selected roots will be represented, their measured logical bytes and observation time;
• which files/locations are excluded, inaccessible, changed, linked or beyond limits, and the practical loss of coverage;
• the recovery purpose, required retention and what will remain protected;
• the exact private owned destination, archive/manifest/probe artifacts, capacity checks and known limits;
• the supported restoration method, verification requirements, costs and unverified assumptions.

The destination must lie outside every source root and proposed cleanup target, even if a source is inside work/. Do not include a previous backup, manifest, output directory, restoration probe or the toolkit source through recursive selection. Do not relocate a destination silently when it is invalid. Current local helper output is limited to private owned work/; an owner-chosen external folder/device/cloud destination needs a separately supported, explicit transfer plan and verification. No automatic upload or hidden extra copy is permitted.

ZIP compression is not encryption. State that plainly before copying sensitive nonsecret data. An external destination being owner-selected does not itself establish privacy, encryption, price or restore reliability. Do not promise compression ratio, elapsed time, paid/cloud cost or final net free space before measurement; give a justified range only if evidence supports it, otherwise say unknown. Include peak disk demand from the ZIP, retained originals, manifest, restoration probe and evidence. A backup can reduce free space before any cleanup; same-volume quarantine normally reclaims none.

Honor the after-analysis, after-selection and before-backup checkpoints selected by the owner. Keep the exact reviewed content/exclusion record and immutable plan/hash private under the owned output root.

4. Bind actual authority and independent review

Review the exact content-bound plan, not a generic statement that backups are good. Compatibility/data review challenges omissions, unique data, source consistency, retained hardlinks, usable restoration, space and retention dependencies. Evidence/security review challenges root admission, protected exclusions, source freshness, link traversal, safe ZIP entry names, manifests, privacy and claims unsupported by capability tests. Resolve revisions or inconclusive findings before mutation. Reviewer approval is not the owner's instruction.

Keep the storage helper plan/digest distinct from the engine's action-plan document/digest. Register exact helper-plan bytes as owned evidence and use the documented engine action schema; the fixed coordinator adapter binds that engine action to the reviewed helper-plan digest, targets and destination. Do not pass a storage plan as an arbitrary engine schema or execute any command field. Register current evidence, the concrete engine plan and both reviews. Bind the actual current owner's instruction to its action IDs and engine plan SHA-256 with approve_plan, unless the engine accepts an already-authorized narrow standing policy for the exact backup-create target/action; preserve real message provenance. Restoration and permanent purge are outside the current automatic standing-policy kinds and need their actual specific decisions. Do not authenticate consent with an old quotation, imported JSON, approved=true, model-generated owner text, a reviewer pass or a scheduled trigger. The owner can use ordinary language to approve a clearly identified plan or subset; the coordinator handles technical identifiers.

Guided/automatic control and now/scheduled timing are independent. Offer checkpoints after analysis, after selection, before backup, after backup verification, before deletion that relies on recovery and after restoration verification. Automatic work stays inside an actual exact-plan approval or valid standing policy bounded to supported kinds, exact targets, count and expiry; independent review, matching scope/settings, recovery, freshness and protected consent still apply. Changed roots, content selections, exclusions, destination, retention, timing effects or material source state invalidate affected plans and need current review and human binding outside any still-valid narrow policy. Do not repeatedly ask for unchanged routine approvals.

PatchCairn: start, help, status, options, cost, settings, pause, resume, stop and resolve use deterministic engine handlers. They are conversation commands, not host slash commands or a generic command interpreter. Scheduling configuration is a proposal; do not create a host schedule or cloud transfer without separate actual authorization and supported capability.

Use supported engine checkpoint keys: scope confirms selection before collection; findings means after analysis; plan means after reviewed selection; before_action on the backup action means before backup; after_action on the recovery step means after backup verification only when actual archive and required probe evidence is present; before_action on cleanup/purge means before deletion; and finish follows final restoration/behavior verification. Handle per-action gates sequentially. A selected checkpoint waits for an actual owner continue decision even in automatic mode; a gate cannot be resolved by the assistant's preference. Do not invent after_backup_verification flags or claim an unsupported boundary is enforced. If the current adapter cannot enforce a selected checkpoint, hold at that boundary and explain the missing capability.

5. Create the bounded immutable copy

Immediately before the operation, recheck exact source identity/content, scope, plan hash, safe-read capability, output ownership, destination outside source/cleanup roots, capacity, quiet workspace and recovery/retention requirements. A material change produces a hold and new plan; do not silently skip a planned file and call the old backup complete.

Call the engine's begin_operation for the exact action/plan and current precondition evidence. Preserve the durable operation ID before create_backup(plan=..., expected_plan_sha256=...). Use only the documented helper with fixed safe entry names and bounded reads. The helper's low-level plan hash checks do not replace actual coordinator authority. Do not overwrite a previous ZIP/manifest, run a command stored in JSON or create an unregistered alternate archive when the intended operation refuses.

Preserve the helper's immutable ZIP and separate manifest and its actual per-attempt receipts. If any source changes, content read fails, output conflicts or limits/capabilities are insufficient, preserve evidence and the truthful partial/failed/unknown outcome. Never advertise an unverified partial artifact as the required recovery copy. Record fresh outcome evidence through finish_operation; a return code or file's existence alone is insufficient.

6. Verify the archive and restoration probe

Use verify_backup(receipt=...) with the exact original receipt and its expected archive/manifest bindings. Its result includes archive bytes for the internal restore path; never print, upload or copy those bytes into a chat/report. Verification must check the archive bytes, full SHA-256 content hashes and exact manifest/entry set, rejecting missing, duplicate, extra, unsafe or changed entries. A ZIP listing, CRC-only check, source hash, stored “verified” flag or successful creation call alone does not establish recovery. Keep actual measured archive/probe sizes separate from planned source logical bytes.

For an integrated backup-create action, bind the exact restore_probe_destination in its reviewed adapter payload before approval. The fixed service persists a derived plan_restore(receipt=..., destination=...) and runs restore_backup(plan=..., expected_plan_sha256=...) there as the backup action's explicitly approved verification substep. This establishes the first actual recovery evidence without requiring a previous backup of that backup; it is not permission for an arbitrary nested restore. An independent restoration action still needs its own exact reviewed engine plan and required-recovery gate. The probe must be a new owned work/ destination outside all source/cleanup targets. No overwrite, path traversal, link extraction or restoration into a live source is permitted. Verify restored file bytes against the manifest and record actual failures/exclusions. A helper refusal is a hold; do not fall back to a generic unzip/extractall or move command. This verifies file contents, not original ACLs, ownership, timestamps, extended attributes, sparse allocation, executable semantics, empty directories or application/system-image consistency.

At the after-backup-verification checkpoint, explain exactly what passed: the immutable selected-file archive and its probe, the observed content coverage, and the remaining limits. Application behavior, metadata/permissions, operating-system bootability or independent-disk recovery remain unverified unless separate evidence establishes them. If the probe cannot run, say the backup is not yet verified for the required purpose and hold any dependent cleanup. Preserve required recovery until that dependency is actually released.

Dependent required-recovery cleanup must pass the actual completed restore_backup receipt as plan_cleanup's recovery_verification, alongside recovery_backup. The current helper reopens the immutable restoration outcome and verifies still-unchanged probe bytes; an archive check or fabricated verified field cannot substitute. Retain and protect that probe while dependent quarantine/purge requires it. All service output artifacts remain categorically ineligible as host-cleanup targets.

7. Restore for a real recovery

First identify the intended recovery: verify an existing backup, restore selected ZIP contents into a new owned location, or reverse quarantine. Use the exact original archive/manifest or quarantine receipts and their immutable bindings. Never use a filename or imported report alone as authority. Explain the destination and the consequence of each choice before asking for it.

For ZIP recovery, verify the archive again, create a new exact reviewed restore plan, obtain actual action approval and pass the engine operation gate. The current helper restores only into a new reviewed owned destination; it does not overwrite a live original folder. A later placement or application import outside that capability needs a separate supported, reviewed, authorized action. Do not choose a new external destination on the owner's behalf.

For quarantine recovery, use plan_quarantine_restore and restore_quarantine under a fresh exact plan and current engine gate. The original admitted root and target identity must still be valid, and the target must not exist. A collision, changed source root, missing artifact or unsupported safe move is a hold; do not overwrite, merge, force rename, cross-volume copy-delete or repair permissions. Verify the restored bytes and record what remains unknown about application behavior.

Keep original recovery artifacts protected through outcome verification. Show the after-restoration-verification checkpoint and the next practical action, such as reviewing the restored files in the new location. Do not treat a restore receipt alone as permission to purge the backup.

8. Pause and resume from actual state

pause immediately prevents new operations; allow active work to reach a safe checkpoint and retain its actual result. Do not kill an operation and claim it changed nothing. stop preserves evidence and unresolved work. Before interruption, preserve the current session revision, operation/action/plan identity, source and destination bindings, partial artifacts, helper receipts, verification performed and pending checks.

On resume, use the same validated session and fresh bounded observations of source/archive/manifest/probe/quarantine state. Reconcile an interrupted operation before more changes. Unknown, failed and partial outcomes remain held; never blindly retry a consumed action, overwrite its artifacts or fabricate success with resolve. That command addresses a named pending decision or records bounded reconciliation evidence. An independently reviewed recovery action may be needed. A scheduled trigger neither duplicates active work nor silently resumes a paused session.

9. Retain, release and report

Keep required recovery, selected retention exclusions and evidence protected even after a session or run is closed. Explain what is retained, where within the private owned output it is stored, measured size, recovery limits and what deletion would lose. The current service has no general session-deletion or required-retention-release executor. Retain its protected artifacts when no supported cleanup path exists; do not send them through assessment-record housekeeping. Only an eligible matching assessment-record run can use its separate reviewed recovery-release bookkeeping, which does not itself approve deletion. Follow RECOVERY_AND_CLEANUP.md for the exact record-family contract rather than editing ownership or retention records by hand.

Permanent purge is a separate irreversible plan, not an extension of backup, restore, quarantine or automatic-mode approval. Obtain actual explicit acknowledgment of losing the exact recovery bytes and restoration opportunity and approval for the exact purge plan. Needed recovery, unresolved operations, protected/excluded data and unknown artifacts cannot be made disposable by a broad purge request. Use only the eligible documented purge helper or the appropriate owned-run cleanup contract; no generic recursive remove, global prune, ACL repair or hidden off-site copy.

The current storage plan_purge/purge_quarantine methods remove exact eligible quarantine files, not backup ZIPs, manifests, evidence or entire runs. Backup artifact deletion needs an actually supported owned-artifact cleanup path with the correct ownership/backend/retention records. If that path or required registration is absent, hold deletion and explain the gap; never invent a backup-purge method, hand-edit a retention flag, or send new artifacts through another backend as a workaround.

Close in ordinary language with exact selected coverage, exclusions/unreadable scope, archive and probe verification, actual restored result, measured storage use, remaining unknowns, protected retention and next choices. Link the private readable report when available. Do not claim full-system protection, encryption, remote redundancy, guaranteed recovery or space savings beyond the actual evidence.

If the job stayed in eligible assessment-only preparation, use complete_assessment only after all agreed assessment/recovery-planning stages and prior checkpoints finish. The engine requires current scope authority and applicable schedule activation; no operation history, plan, approval, reviews or standing policy; an owned typed findings/limitations summary; separate fresh verification bound to its exact hash/evidence coverage; and the actual owner's closeout instruction. A selected finish checkpoint still waits for the owner's continue decision. This is a recorded assessment with no maintenance action, not evidence that a backup or restoration occurred. If the session is ineligible or unfinished, stop and preserve its findings under the actual contract. Never create a pretend backup action to reach completed status.

Developed by Michael. Private session records belong locally under work/; this public guide contains no live computer records.