Integrity Enforcement

Holy Resource includes an integrity enforcement layer that helps detect when the app no longer trusts the current working data exactly as expected.

This protection exists to reduce the risk of silent corruption, accidental overwrites, or unexpected changes that could otherwise go unnoticed until much later.

Integrity enforcement is about the trust state of the workspace itself. It is not meant to interrupt routine table-level work such as ordinary CSV/XLSX imports, standard exports, report generation, or printing.

What Integrity Enforcement Does

Before normal work continues, Holy Resource verifies that critical parts of the workspace still match the trusted state that was previously established.

If everything matches, the app opens normally.

If something important no longer matches, Holy Resource can pause normal access and place the workspace into a guarded recovery flow instead of continuing as if nothing happened.

In other words, integrity enforcement is checking whether the app still trusts the current working state as the same trusted workspace it expected to open.

Why This Matters

Integrity enforcement is designed to protect churches from high-impact situations such as:

• incomplete restores from older copies
• unexpected file-level changes outside normal app usage
• data mismatches introduced during storage moves or device problems
• partial recoveries that look normal at first but are missing trusted state

The goal is not to block work unnecessarily. The goal is to stop quietly-trusted data from being treated as healthy when it may not be.

That is also why the scope matters. This layer is intended for high-trust storage and restore concerns. It is not intended to treat every import/export action as if a whole workspace replacement is happening.

What Integrity Enforcement Usually Applies To

Integrity enforcement is most relevant when the church may be opening or continuing from a workspace whose trusted state is now uncertain.

Examples include:

• opening after files were moved or replaced outside the app
• continuing after a manual restore or copy-over operation
• recovering from a storage or device problem
• resuming from a partial migration or interrupted recovery process

What Integrity Enforcement Does Not Usually Apply To

Routine operational work should not normally trigger integrity recovery just because the action touches data inside the app.

That includes:

• importing a CSV into a module table
• importing an Excel file into a module table
• exporting CSV, Excel, or PDF reports
• printing a table view
• using Smart Import header mapping
• previewing an import report

If a team sees an integrity mismatch or recovery-mode interruption while doing an ordinary module import, that should be treated as unusual behavior and investigated rather than accepted as normal.

What Recovery Mode Means

If Holy Resource detects a serious mismatch, it can enter recovery mode.

Recovery mode is a protective state. It gives administrators a chance to review the situation, create a safety backup, and decide the right next step before ordinary work resumes.

In practice, this means:

• day-to-day work is paused until the issue is reviewed
• administrators can create a fresh backup before making changes
• Holy Resource may already have an automatic startup backup from just before a schema upgrade
• trusted staff can confirm whether the current state is expected
• the workspace can be re-accepted only after review

Recovery Mode also includes a short Restore database safely reminder inside the app. It is there because manual database copies are one of the most common reasons teams end up guessing their way through recovery.

On the Recovery Mode screen, the main actions are:

• Retry Check
• Create Backup
• Restore Latest Upgrade Backup
• Reset Integrity Baseline

The last two actions are admin-only recovery steps and require global admin credentials. If the restore succeeds, Holy Resource relaunches immediately so the restored database is reopened cleanly.

When a Church Should Re-Accept the Current State

Administrators should only re-accept the current state when they are confident that the present data is the correct data to keep using.

Examples include:

• a planned restore from a known-good backup
• a verified migration to a replacement machine
• an intentional administrative recovery step that the church has reviewed

If there is doubt, create a backup first and review with the people responsible for records, finance, or operations before proceeding.

In practical terms, re-accepting the current state usually means using Reset Integrity Baseline after you have confirmed that the current database is the one your church wants to keep using.

That action does not rewrite the current data. It updates Holy Resource's trusted integrity baseline so the app treats the present database as the accepted state going forward.

Step-By-Step Solution For Recovery Mode

If a non-technical administrator sees an integrity mismatch, use this order.

Safe path when you believe the current data is correct

1. Read the message on the Recovery Mode screen and note the mismatched scopes if they are listed.
2. Press Create Backup first.
3. Wait until the app shows the backup path and confirms that the backup was created.
4. If the problem started right after an app update and you want to go back to the last pre-upgrade copy, use Restore Latest Upgrade Backup instead of manually copying files.
5. Enter the global admin License Key, Username, and Password, then run the restore.
6. Holy Resource relaunches after a successful restore so it can reconnect to the restored database and run its checks again.
7. Ask a simple business question: "Is the data on this machine the correct data we want to keep using?"
8. If the answer is yes, enter the global admin License Key, Username, and Password.
9. Press Reset Integrity Baseline.
10. After the reset completes, Holy Resource automatically runs the integrity check again.
11. If the reset succeeds and the current database is now trusted, the app should leave Recovery Mode and continue normally.
12. Use Retry Check only if you want to run the check again manually after a restart or another review step.

If this situation started after someone manually copied the database into the app-data folder, also confirm the restore was done safely:

13. Make sure Holy Resource was fully closed before the files were copied.
14. Make sure holy_resource.db was copied together with holy_resource.db-wal and holy_resource.db-shm if those sidecar files existed at the time of the copy.
15. If only the main database file was copied but the matching sidecars were left behind on the source machine, treat the copied database as potentially incomplete until you review it.

This is the normal resolution path after an intentional restore, a verified device migration, or another reviewed recovery event.

Safe path when you are not sure the current data is correct

1. Press Create Backup immediately.
2. Do not reset the baseline yet.
3. Compare the current machine with your most recent known-good backup.
4. Ask the church admin or records/finance lead whether recent changes were expected.
5. Only use Reset Integrity Baseline after someone responsible confirms that this is the correct database to trust.

If the mismatch appeared during normal import/export work

Routine table imports and exports should not normally trigger Recovery Mode.

If this happened during an ordinary module import or export:

1. Stop the current task.
2. Close and reopen Holy Resource once.
3. Press Retry Check.
4. If Recovery Mode remains, press Create Backup before doing anything else.
5. Confirm whether someone recently restored a backup, copied files manually, changed storage locations, or moved the database to another machine.
6. If none of that happened and the issue began during a normal CSV/XLSX import, treat it as unusual and escalate with the exact message shown on screen.

If the mismatch appeared after a manual database copy or restore

Use this checklist before resetting trust:

1. Close Holy Resource on every machine that might still be using that same database.
2. Confirm the copied file is the correct holy_resource.db for the church you intended to restore.
3. Check whether the source folder also had holy_resource.db-wal and holy_resource.db-shm.
4. If those sidecar files existed, copy them with the database as one matching set.
5. Reopen Holy Resource and read the details on the Recovery Mode screen.
6. Create a backup immediately from Recovery Mode.
7. Only use Reset Integrity Baseline after the church confirms this is the exact database state it wants to keep using.

What Each Recovery Button Really Means

Retry Check

Use this after a restart or after an admin recovery step. It tells Holy Resource to run the integrity check again.

This is the safest first button because it does not change data.

Create Backup

Use this before resetting the baseline or before asking someone else to review the problem.

This creates a safety copy of the current state so you still have something to go back to if the current database turns out to be the wrong one.

If you reached Recovery Mode after copying files manually, creating this backup gives you a safe checkpoint before you try anything else.

Restore Latest Upgrade Backup

Use this when the problem started immediately after an app update and you want Holy Resource to roll back to the last automatic backup it made before running startup schema changes.

This avoids manual file-copy steps. Holy Resource restores the latest startup-upgrade backup for you and tells you to relaunch afterward. On desktop builds, the app attempts that relaunch automatically right after the restore completes.

This is meant for upgrade recovery, not ordinary table import/export work.

Reset Integrity Baseline

Use this only after an administrator confirms that the current data is the right data.

Think of this as saying:

"Holy Resource, this database is correct. Trust this as the new baseline from now on."

This is why the app asks for global admin credentials. It is a controlled trust decision, not an everyday button.

Simple Decision Guide

Use this quick rule:

• If the current data is correct and you can prove it, create a backup and then reset the integrity baseline.
• If the current data may be wrong, create a backup and stop there until the church reviews it.
• If the mismatch appeared during an ordinary table import/export, retry once and then investigate instead of blindly resetting trust.

Recommended Response When a Mismatch Appears

1. Stop and avoid making extra changes until the issue is understood.
2. Create a backup of the current state immediately.
3. Confirm whether the device, storage location, or copied files changed recently.
4. Compare the current situation with your most recent trusted backup.
5. If the current database is confirmed to be correct, enter global admin credentials and use Reset Integrity Baseline.
6. Allow Holy Resource to re-check integrity automatically after the reset.
7. Use Retry Check only if you need to run the check again manually.

If the mismatch appeared during what should have been ordinary table import/export work, add one more check before re-accepting anything:

8. Confirm whether the event was actually a routine module import/export workflow or whether a larger restore, file move, or workspace replacement happened at the same time.

Good Operating Habits

• Keep at least one recent backup outside the primary working device.
• Limit who can move, replace, or overwrite church data files.
• When moving a database manually, copy holy_resource.db, holy_resource.db-wal, and holy_resource.db-shm together whenever the sidecar files exist.
• Record planned restore or migration events so staff know when a change was intentional.
• Treat unexpected recovery mode prompts as a real operational signal, not just a nuisance prompt.
• Teach staff the difference between routine table import/export and workspace-level restore or recovery operations.

Practical Rule Of Thumb

Ask one simple question:

Is the team only importing or exporting rows inside a normal module screen, or are they changing which trusted workspace the app is opening?

If it is only a normal module import/export workflow, integrity enforcement should generally stay out of the way.

If the app is being asked to trust a changed or replaced workspace, recovery behavior may be appropriate.

Related

• Security model: /docs/security/security-model
• Encryption: /docs/security/security-model
• Backups: /docs/operations/backups