slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/construction/u2-data-durability/functional-design/business-rules.md

Business Rules — U2 Data Durability

---

Migration Decision Logic

graph TD
    start["Startup: migrate ApplicationDbContext"]
    attempt["Attempt migration"]
    ok{"Succeeded ?"}
    done["Continue startup"]
    kind{"Failure kind ?"}
    attempts{"Retry attempts remaining ?"}
    wait["Wait with increasing delay"]
    logfail["Log the failure with context"]
    stop["Propagate: process does not start"]

    start --> attempt
    attempt --> ok
    ok -->|yes| done
    ok -->|no| kind
    kind -->|"connection failure"| attempts
    kind -->|"migration failure"| logfail
    attempts -->|yes| wait
    attempts -->|no| logfail
    wait --> attempt
    logfail --> stop

    classDef entry fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
    classDef decision fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef good fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef bad fill:#fbb6ce,stroke:#b83280,stroke-width:1px,color:#000;
    class start entry;
    class ok,kind,attempts decision;
    class attempt,wait,done good;
    class logfail,stop bad;

Text alternative: migration is retried with increasing delay only when the failure is a connection problem; a genuine migration failure is logged and stops the process immediately, as does exhausting the retry attempts.

---

Key Ring Durability Rules

ID	Rule
BR-U2-01	Data Protection keys are persisted in the database, in the context that owns Identity — never on the filesystem.
BR-U2-02	The application discriminator is a fixed constant in code. It is not derived from any path, and it is not configurable.
BR-U2-03	Data Protection is configured exactly once, by the host, before module service registration.
BR-U2-04	No module may call AddDataProtection(). Modules consume IDataProtector only.
BR-U2-05	Key lifetime uses the framework default of 90 days, with automatic rotation.
BR-U2-06	Old keys are never deleted. Removing a key makes every value encrypted with it permanently unreadable, including stored slave API keys.
BR-U2-07	Keys are stored unencrypted at rest in the database. This is an accepted, documented deviation — see DEV-05.
BR-U2-08	The database connection must enforce TLS, and the database must not be publicly reachable. These are the compensating controls for BR-U2-07.

Rationale for BR-U2-02: the default discriminator derives from the content root path, which changes on every atomic release switch. Persisting keys in the database while letting the discriminator move produces keys that are stored but underivable — the same failure, quieter. A constant cannot be forgotten during a host migration or accidentally differ between two instances sharing a database.

Rationale for BR-U2-03 and BR-U2-04: this is the § 5.1 conflict. Because module registration runs after the host's, a module's bare AddDataProtection() would override the persistent store. IDataProtector still resolves, so registration tests pass — the defect appears only after the first release switch, as slave API keys that no longer decrypt.

Rationale for BR-U2-06: this is the single most destructive maintenance action available against this system. Pruning the keys table looks like harmless housekeeping and permanently breaks every Master↔slave relationship. It must be stated in the deployment documentation, not only in code comments (Q5 = C).

---

Migration Rules

ID	Rule
BR-U2-09	ApplicationDbContext migrations are applied automatically at startup, before the application accepts traffic.
BR-U2-10	Core migrations run before module middleware installation, so the keys table exists before any module resolves an IDataProtector.
BR-U2-11	A connection failure is retried with increasing delay, up to a bounded number of attempts.
BR-U2-12	A migration failure — invalid, conflicting, or inapplicable — fails immediately with no retry.
BR-U2-13	When retries are exhausted, or on a migration failure, the exception propagates and the process does not start.
BR-U2-14	Before failing, the reason is logged with enough context to diagnose it — but never including the connection string, credentials, or any secret.
BR-U2-15	AvailabilityDbContext and MasterDbContext keep their existing self-migration in UseModule. U2 does not change them.
BR-U2-16	Migrations must be forward-compatible and non-destructive, so redeploying an earlier release remains a valid rollback.

Rationale for BR-U2-11 and BR-U2-12: the two failures mean different things. On the Pi the application and SQL Server may start together after a reboot, so a brief unavailability window is normal operation, not a fault. A broken migration is a fault, and retrying it only delays the inevitable while filling the log.

Rationale for BR-U2-13: this is what gives U1's liveness check meaning. A process that starts regardless would report healthy while being unusable; strict startup makes the absence of a /health response a trustworthy signal.

Rationale for BR-U2-16: rollback is "redeploy the previous release" (D-26). That is only safe if the older code can run against the newer schema. A destructive migration — dropping a column, narrowing a type — makes rollback impossible precisely when it is most needed.

---

Operational Constraint Rules

ID	Rule
BR-U2-17	Exactly one application instance may migrate a given database at a time. Not enforced in code; documented as an operational constraint (Q4 = C).
BR-U2-18	Each instance has its own database. The Master and each slave never share one.

Rationale: Database.Migrate() is not safe under concurrency. Today the constraint holds by design — one instance per database — so a distributed lock would add failure modes without removing any. Should the deployment model ever change to multiple instances sharing a database, automatic startup migration must be revisited before that change is made.

---

Error and Edge-Case Scenarios

Scenario	Expected behaviour
Fresh database, no tables	All Core migrations applied, including the keys table; startup proceeds
Database up to date	Migration is a no-op; startup proceeds
Database unreachable at startup, comes up within the retry window	Retries succeed; startup proceeds; the delay is logged
Database unreachable for the whole retry window	Logged, process does not start, /health silent, UptimeRobot red
Migration conflicts with existing schema	Failed immediately, no retry, process does not start
Credentials wrong	Treated as a connection failure — retried, then fails. Distinguishing bad credentials from an unreachable server is not worth the complexity; the outcome is identical
Keys table empty on first run	Data Protection generates a key and persists it; normal first-run behaviour
Keys table populated from a previous release	Existing keys are read; previously encrypted values remain readable — the purpose of the unit
Release directory changed since last start	Irrelevant — the discriminator is a constant (BR-U2-02)
Someone deletes rows from the keys table	Every value encrypted with those keys becomes permanently unreadable. Prevented by documentation only (BR-U2-06)
Two instances start simultaneously against one database	Undefined. Prevented by the operational constraint (BR-U2-17), not by code
A module still calls AddDataProtection() after this unit	The persistent store is silently overridden. Prevented by BR-U2-04 and asserted by a test

---

Security Compliance for U2

Rule	Status	Notes
SECURITY-01	Partially compliant — DEV-05	Encryption in transit enforced by BR-U2-08 (TLS on the connection). Encryption at rest for the keys themselves is deferred: keys are stored unencrypted, relying on the database's own at-rest encryption and network isolation. Accepted with a follow-up (Q2 = C)
SECURITY-03	Compliant	BR-U2-14 requires diagnostic context without secrets
SECURITY-09	Compliant	No default credentials; failure messages carry no connection details
SECURITY-13	Improved	The key ring surviving redeploys is precisely a software-integrity property: without it, the encrypted API keys that authenticate Master↔slave communication silently become invalid
SECURITY-15	Compliant	Fails closed — the process does not start rather than serving in an unknown schema state

New Documented Deviation

ID	Deviation	Rationale	Decided
DEV-05	Data Protection keys are stored unencrypted at rest. SECURITY-01 requires encryption at rest for persisted data.	DPAPI is unavailable on Linux, and X.509 certificate encryption relocates the loss problem to the certificate — reintroducing the failure mode this unit exists to eliminate. Compensating controls: TLS on the database connection, and the database not publicly reachable (BR-U2-08). Certificate-based encryption is recorded as a separate follow-up item.	Q2 = C