Skip to content

Retention Capability (Flow)

This capability describes how SmrtHub applies retention policies and legal holds end-to-end, and how operators export verifiable evidence.

Purpose and scope

  • Defines the end-to-end operator flows for retention policy management, legal holds, and evidence export.
  • Covers canonical paths, control surfaces, and evidence artifacts.
  • Does not define subsystem invariants or storage/evidence contracts in full detail (see Subsystem doc).

Canonical references

Entry points

  • SmrtHubSupervisor.exe (operator CLI): apply policies, manage holds, export evidence.
  • Smrt.StorageGuard.ServiceHost (scheduled host): produces verification evidence artifacts.
  • Smrt.SupportBundle: packages retention state/evidence for operator export and review.

Participating components and subsystems

  • Operator (IT / Compliance / Support)
  • SmrtHubSupervisor (control plane)
  • Smrt.StorageGuard.ServiceHost (verification evidence producer)
  • Smrt.SupportBundle (packaging + reporting)
  • Providers (OneDrive/SharePoint/SMB/local archive; future)

Contracts and data

Retention workflows rely on the Retention Subsystem contracts: - Retention policy configuration JSON. - Legal holds configuration JSON. - Evidence payloads (verification results, health) and optional signatures.

Configuration and operational data

Canonical storage locations are defined by the Retention Subsystem. At a minimum, operators should expect: - Retention config under %ProgramData%/SmrtHub/Config/retention/. - Evidence artifacts under %ProgramData%/SmrtHub/Logs/system-info/retention/. - Support Bundle export staging under system-info/retention/ inside the bundle.

Sequence / flow

Flow 1: Configure retention policies

Sources of configuration: - Today: operator-edited JSON in the canonical retention config folder. - Future: HubWindow WinUI settings page.

Preferred application path: 1. Operator prepares a full retention configuration JSON. 2. Operator runs SmrtHubSupervisor.exe --retention-apply --configuration <path> [--updated-by <id>]. 3. Supervisor validates and persists the config via Smrt.Retention using atomic writes. 4. Supervisor reports the effective policy state in --retention-status.

Outcomes: - retention-policy.json reflects the current effective policy. - Audit metadata (updated by/when) is persisted as part of the configuration model.

Add a hold: 1. Operator runs SmrtHubSupervisor.exe --legal-hold-add --name <str> --scope <str> [options]. 2. Supervisor validates the hold and persists it. 3. Hold becomes effective immediately: future purge planning (present/future) must exclude matching artifacts.

Clear a hold: 1. Operator runs SmrtHubSupervisor.exe --legal-hold-clear --id <guid>. 2. Supervisor blocks removal of system-generated holds when applicable.

Flow 3: Scheduled verification and evidence emission

  1. Smrt.StorageGuard.ServiceHost loads the active retention policies + holds.
  2. The host runs a retention verification worker on a fixed cadence.
  3. The worker emits:
  4. retention-verification.json (structured results)
  5. retention-verification.sig (when signing is enabled)
  6. retention-health.json (rolling status and consecutive failures)
  7. The worker logs operational telemetry under the retention-verifier slug.

Success criteria: - Evidence files are written to the canonical system-info/retention/ folder. - The evidence payload includes hashes of policies and holds for correlation.

Flow 4: Operator export and compliance evidence

Export retention evidence (CLI): 1. Operator runs SmrtHubSupervisor.exe --retention-export [--output <dir>]. 2. Supervisor copies current config + most recent evidence artifacts into a timestamped export directory. 3. Operator attaches the export to the compliance ticket or secured share.

Export retention evidence (Support Bundle): 1. Operator generates a Support Bundle with ExportCategories.SystemInfo enabled. 2. The bundle stages: - system-info/retention/retention-policy.json - system-info/retention/legal-holds.json - system-info/retention/retention-verification.json + .sig - system-info/retention/retention-health.json - provider automation logs when present 3. The bundle manifest and review reports summarize retention evidence to reduce manual review effort.

Flow 5: Automation triggers (Supervisor)

Supervisor may export retention evidence automatically when: - Storage Guard reports quota risk (warning/critical). - Storage Guard reports ACL drift above configured thresholds.

This ensures that evidence is captured close to an incident timeline without relying on manual operator action.

Observability and diagnostics

  • Storage Guard retention verification logs use the retention-verifier slug.
  • SmrtHubSupervisor.exe --retention-status surfaces the effective policy + hold state and basic health.
  • Support Bundle exports should include retention config + evidence when ExportCategories.SystemInfo is enabled.

Failure modes and recovery

  • Invalid retention JSON: re-run --retention-apply with validated configuration and confirm canonical paths are accessible.
  • Consecutive verification failures: collect retention-verifier logs and the latest evidence payload before remediation.
  • Missing evidence in Support Bundle output: confirm Storage Guard has produced evidence in %ProgramData%/SmrtHub/Logs/system-info/retention/ and re-run export with appropriate privileges.

Testing and validation

  • Unit tests: SmrtApps/tests/Smrt.Retention.Tests/README.md
  • End-to-end validation: apply a known policy, add a legal hold, confirm evidence artifacts are produced, then confirm Support Bundle includes system-info/retention/ artifacts.