Skip to content

Commit 5f41d1e

Browse files
ToolboxAidToolboxAid
committed
Add Backup Snapshot and Restore Request contract tests as separate boundaries - PR_26152_092-backup-restore-contract-tests
1 parent 1d12cba commit 5f41d1e

10 files changed

Lines changed: 2186 additions & 0 deletions

‎docs/dev/reports/backup_snapshot_contract_tests_validation.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Backup Snapshot Contract Tests Validation
2+
3+
PR: PR_26152_092-backup-restore-contract-tests
4+
5+
## Scope
6+
7+
- Added `src/shared/contracts/backupSnapshotContract.js`.
8+
- Added `tests/shared/BackupSnapshotContract.test.mjs`.
9+
- Added `tests/fixtures/backup-snapshots/backup-snapshot-scenarios.json`.
10+
- Added `docs/dev/specs/BACKUP_SNAPSHOT_CONTRACT.md`.
11+
- Backup Snapshot contract remains metadata-only and does not contain runtime state, toolState, file bytes, auth session state, installer state, updater implementation details, or storage implementation details.
12+
13+
## Lanes Executed
14+
15+
- contract - backup snapshot contract syntax and targeted fixture validation.
16+
- contract dependencies - migration plan, version compatibility, update channel, install receipt, library item, project, and identity/permissions contract compatibility.
17+
18+
## Lanes Skipped
19+
20+
- runtime - no runtime behavior changed.
21+
- UI/CSS/HTML - no UI, CSS, or HTML files changed.
22+
- samples - samples are out of scope for contract-only validation.
23+
- repo-wide tests - explicitly out of scope.
24+
25+
## Commands
26+
27+
- PASS: `node --check src/shared/contracts/backupSnapshotContract.js`
28+
- PASS: `node --check tests/shared/BackupSnapshotContract.test.mjs`
29+
- PASS: `node tests/shared/BackupSnapshotContract.test.mjs`
30+
- PASS: `node tests/shared/MigrationPlanContract.test.mjs`
31+
- PASS: `node tests/shared/VersionCompatibilityContract.test.mjs`
32+
- PASS: `node tests/shared/UpdateChannelContract.test.mjs`
33+
- PASS: `node tests/shared/InstallReceiptContract.test.mjs`
34+
- PASS: `node tests/shared/LibraryItemContract.test.mjs`
35+
- PASS: `node tests/shared/ProjectContract.test.mjs`
36+
- PASS: `node tests/shared/IdentityPermissionsContract.test.mjs`
37+
38+
## Expected PASS Behavior
39+
40+
- Valid backup snapshot fixtures pass.
41+
- Invalid backup snapshot fixtures reject missing owner/project/link records, mismatched release/publish/library/install/migration linkage, invalid snapshot/schema versions, and forbidden runtime/tool/file/auth/installer/updater/storage fields.
42+
- Existing dependent contract tests remain compatible.
43+
44+
## Expected WARN Behavior
45+
46+
- None.
47+

‎docs/dev/reports/restore_request_contract_tests_validation.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Restore Request Contract Tests Validation
2+
3+
PR: PR_26152_092-backup-restore-contract-tests
4+
5+
## Scope
6+
7+
- Added `src/shared/contracts/restoreRequestContract.js`.
8+
- Added `tests/shared/RestoreRequestContract.test.mjs`.
9+
- Added `tests/fixtures/restore-requests/restore-request-scenarios.json`.
10+
- Added `docs/dev/specs/RESTORE_REQUEST_CONTRACT.md`.
11+
- Restore Request contract remains metadata-only and does not contain runtime state, toolState, file bytes, auth session state, installer state, updater implementation details, or storage implementation details.
12+
13+
## Lanes Executed
14+
15+
- contract - restore request contract syntax and targeted fixture validation.
16+
- contract dependencies - migration plan, version compatibility, update channel, install receipt, library item, project, and identity/permissions contract compatibility.
17+
18+
## Lanes Skipped
19+
20+
- runtime - no runtime behavior changed.
21+
- UI/CSS/HTML - no UI, CSS, or HTML files changed.
22+
- samples - samples are out of scope for contract-only validation.
23+
- repo-wide tests - explicitly out of scope.
24+
25+
## Commands
26+
27+
- PASS: `node --check src/shared/contracts/restoreRequestContract.js`
28+
- PASS: `node --check tests/shared/RestoreRequestContract.test.mjs`
29+
- PASS: `node tests/shared/RestoreRequestContract.test.mjs`
30+
- PASS: `node tests/shared/MigrationPlanContract.test.mjs`
31+
- PASS: `node tests/shared/VersionCompatibilityContract.test.mjs`
32+
- PASS: `node tests/shared/UpdateChannelContract.test.mjs`
33+
- PASS: `node tests/shared/InstallReceiptContract.test.mjs`
34+
- PASS: `node tests/shared/LibraryItemContract.test.mjs`
35+
- PASS: `node tests/shared/ProjectContract.test.mjs`
36+
- PASS: `node tests/shared/IdentityPermissionsContract.test.mjs`
37+
38+
## Expected PASS Behavior
39+
40+
- Valid restore request fixtures pass.
41+
- Invalid restore request fixtures reject missing owner/project/link records, mismatched backup/release/compatibility linkage, blocked or incompatible compatibility gates, invalid timestamps, and forbidden runtime/tool/file/auth/installer/updater/storage fields.
42+
- Existing dependent contract tests remain compatible.
43+
44+
## Expected WARN Behavior
45+
46+
- None.
47+

‎docs/dev/specs/BACKUP_SNAPSHOT_CONTRACT.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Backup Snapshot Contract
2+
3+
## Purpose
4+
5+
Backup Snapshot records describe a metadata-only backup point for an owned project/release installation path.
6+
7+
The record links the owner, project, release, publish, library item, install receipt, and migration plan records needed to identify what was backed up. It does not store backup payload data, file bytes, runtime state, installer state, updater implementation details, auth session state, or storage implementation details.
8+
9+
## Ownership
10+
11+
- Every Backup Snapshot requires `ownerId`.
12+
- The Backup Snapshot owner must match `libraryItem.ownerId`.
13+
- The Backup Snapshot owner must match `installReceipt.ownerId`.
14+
- The Backup Snapshot owner must match `migrationPlan.ownerId`.
15+
16+
## Required Linkage
17+
18+
- `projectId` links the snapshot to the persisted Project container.
19+
- `sourceRelease` identifies the published or retired Release being backed up.
20+
- `sourcePublish` identifies the published or retired Publish record for the Release.
21+
- `libraryItem` identifies the owner's Library Item.
22+
- `installReceipt` identifies the install receipt that was backed up.
23+
- `migrationPlan` identifies the migration plan governing the installed version/schema.
24+
25+
## Version Rules
26+
27+
- `snapshotVersion` is required and must be a positive integer.
28+
- `schemaVersion` is required and must be a positive integer.
29+
- `snapshotVersion` must match `sourceRelease.version`.
30+
- `snapshotVersion` must match `migrationPlan.targetVersion`.
31+
- `schemaVersion` must match `migrationPlan.schemaVersion`.
32+
33+
## Boundaries
34+
35+
Backup Snapshot records must not contain:
36+
37+
- runtime state
38+
- toolState or tool payloads
39+
- file bytes or encoded file data
40+
- auth session state
41+
- installer state or installer implementation details
42+
- updater state or updater implementation details
43+
- storage provider, bucket, object key, signed URL, CDN, or file path implementation details
44+
45+
## Validation
46+
47+
Targeted validation lives in:
48+
49+
- `src/shared/contracts/backupSnapshotContract.js`
50+
- `tests/shared/BackupSnapshotContract.test.mjs`
51+
- `tests/fixtures/backup-snapshots/backup-snapshot-scenarios.json`
52+

‎docs/dev/specs/RESTORE_REQUEST_CONTRACT.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Restore Request Contract
2+
3+
## Purpose
4+
5+
Restore Request records describe a metadata-only request to restore from a Backup Snapshot into a target Release context.
6+
7+
The record links the restore owner, project, backup snapshot, target release, and version compatibility records. It does not store restore payload data, runtime state, toolState, file bytes, auth session state, installer state, updater implementation details, or storage implementation details.
8+
9+
## Ownership
10+
11+
- Every Restore Request requires `ownerId`.
12+
- The Restore Request owner must match `backupSnapshot.ownerId`.
13+
- The Restore Request owner must match `versionCompatibility.ownerId`.
14+
15+
## Required Linkage
16+
17+
- `projectId` links the request to the persisted Project container.
18+
- `backupSnapshot` identifies the Backup Snapshot selected for restore.
19+
- `targetRelease` identifies the published or retired Release target.
20+
- `versionCompatibility` identifies the compatibility gate for the target restore path.
21+
22+
## Compatibility Rules
23+
24+
- `backupSnapshot.releaseId` must match `targetRelease.releaseId`.
25+
- `versionCompatibility.releaseId` must match `targetRelease.releaseId`.
26+
- `versionCompatibility.publishId` must match `backupSnapshot.publishId`.
27+
- `backupSnapshot.snapshotVersion` must match `targetRelease.version`.
28+
- `backupSnapshot.schemaVersion` must match `versionCompatibility.supportedSchemaVersion`.
29+
- Restore is allowed only when compatibility is `compatible` or `deprecated`.
30+
- `blocked` or `incompatible` compatibility states block restore.
31+
32+
## Boundaries
33+
34+
Restore Request records must not contain:
35+
36+
- runtime state
37+
- toolState or tool payloads
38+
- file bytes or encoded file data
39+
- auth session state
40+
- installer state or installer implementation details
41+
- updater state or updater implementation details
42+
- storage provider, bucket, object key, signed URL, CDN, or file path implementation details
43+
44+
## Validation
45+
46+
Targeted validation lives in:
47+
48+
- `src/shared/contracts/restoreRequestContract.js`
49+
- `tests/shared/RestoreRequestContract.test.mjs`
50+
- `tests/fixtures/restore-requests/restore-request-scenarios.json`
51+

0 commit comments

Comments
 (0)