Skip to content

Commit 1d12cba

Browse files
ToolboxAidToolboxAid
committed
Add Migration Plan contract tests and compatibility gating rules - PR_26152_091-migration-plan-contract-tests
1 parent 34567f0 commit 1d12cba

5 files changed

Lines changed: 1760 additions & 0 deletions

File tree

‎docs/dev/reports/migration_plan_contract_tests_validation.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Migration Plan Contract Tests Validation
2+
3+
PR: `PR_26152_091-migration-plan-contract-tests`
4+
5+
## Scope
6+
7+
- Added Migration Plan contract definition under `src/shared/contracts`.
8+
- Added Migration Plan fixture scenarios.
9+
- Added Migration Plan targeted contract test suite.
10+
- Added Migration Plan contract specification document.
11+
- No database, authentication, installer, updater, migration implementation, file delivery, download, UI, HTML, CSS, or runtime implementation changes.
12+
13+
## Commands
14+
15+
| Command | Result |
16+
| --- | --- |
17+
| `node --check src/shared/contracts/migrationPlanContract.js` | PASS |
18+
| `node --check tests/shared/MigrationPlanContract.test.mjs` | PASS |
19+
| `node tests/shared/MigrationPlanContract.test.mjs` | PASS |
20+
| `node tests/shared/VersionCompatibilityContract.test.mjs` | PASS |
21+
| `node tests/shared/UpdateChannelContract.test.mjs` | PASS |
22+
| `node tests/shared/InstallReceiptContract.test.mjs` | PASS |
23+
| `node tests/shared/LibraryItemContract.test.mjs` | PASS |
24+
| `node tests/shared/DownloadGrantContract.test.mjs` | PASS |
25+
| `node tests/shared/EntitlementContract.test.mjs` | PASS |
26+
| `node tests/shared/MarketplaceListingContract.test.mjs` | PASS |
27+
| `node tests/shared/PublishContract.test.mjs` | PASS |
28+
| `node tests/shared/ReleaseContract.test.mjs` | PASS |
29+
| `node tests/shared/ProjectContract.test.mjs` | PASS |
30+
| `node tests/shared/IdentityPermissionsContract.test.mjs` | PASS |
31+
| `git diff --name-only -- '*.css' '*.html'` | PASS - no CSS or HTML changes |
32+
| `git diff --check` | PASS |
33+
| `npm run codex:review-artifacts` | PASS |
34+
35+
## Contract Coverage
36+
37+
Validated Migration Plan rules:
38+
39+
- Migration Plan requires owner.
40+
- Migration Plan requires project.
41+
- Migration Plan requires target Release linkage.
42+
- Migration Plan requires Version Compatibility linkage.
43+
- Migration Plan requires Update Channel linkage.
44+
- Migration Plan requires Library Item linkage.
45+
- Migration Plan requires Install Receipt linkage.
46+
- `versionCompatibility.ownerId`, `updateChannel.ownerId`, `libraryItem.ownerId`, and `installReceipt.ownerId` must match `ownerId`.
47+
- `targetRelease.projectId`, `versionCompatibility.projectId`, `updateChannel.projectId`, `libraryItem.projectId`, and `installReceipt.projectId` must match `projectId`.
48+
- `versionCompatibility.releaseId`, `updateChannel.releaseId`, `libraryItem.releaseId`, and `installReceipt.releaseId` must match `targetRelease.releaseId`.
49+
- `updateChannel.publishId`, `libraryItem.publishId`, and `installReceipt.publishId` must match `versionCompatibility.publishId`.
50+
- `installReceipt.libraryItemId` must match `libraryItem.libraryItemId`.
51+
- `sourceVersion`, `targetVersion`, and `schemaVersion` must be positive integers.
52+
- `targetVersion` must match `targetRelease.version`.
53+
- `targetVersion` must match `versionCompatibility.targetVersion`.
54+
- `schemaVersion` must match `versionCompatibility.supportedSchemaVersion`.
55+
- Migration state is limited to `notRequired`, `required`, `blocked`, and `completed`.
56+
- `notRequired` requires `sourceVersion` and `targetVersion` to match.
57+
- `required` and `completed` require `targetVersion` to be newer than `sourceVersion`.
58+
- `completed` requires `completedAt`.
59+
- If Version Compatibility is `blocked` or `incompatible`, Migration Plan must be `blocked`.
60+
- Migration Plan access remains owner-private unless platform administration permission applies.
61+
62+
Validated forbidden leakage:
63+
64+
- Runtime state rejected.
65+
- ToolState data rejected.
66+
- Installer state rejected.
67+
- Updater implementation details rejected.
68+
- Migration implementation code rejected.
69+
- File bytes rejected.
70+
- Download state rejected.
71+
72+
## Samples Decision
73+
74+
SKIP. This PR only changes shared contract definitions, contract fixtures, contract tests, docs/specs, and reports. Samples are not in scope.
75+
76+
## Playwright
77+
78+
Playwright impacted: No. This PR has no UI, runtime, tool behavior, rendering, or page changes.
79+
80+
## Manual Validation
81+
82+
1. Review `docs/dev/specs/MIGRATION_PLAN_CONTRACT.md`.
83+
2. Review `src/shared/contracts/migrationPlanContract.js`.
84+
3. Confirm Migration Plan links to Project, target Release, Version Compatibility, Update Channel, Library Item, Install Receipt, and owner records.
85+
4. Confirm migration state validation covers `notRequired`, `required`, `blocked`, and `completed`.
86+
5. Confirm source/target/schema version validation and compatibility gating rules are documented and tested.
87+
6. Confirm Migration Plan does not carry runtime, toolState, installer, updater, migration implementation code, file bytes, or download state.
88+
7. Confirm `docs/dev/reports/codex_review.diff` and `docs/dev/reports/codex_changed_files.txt` exist for review.

‎docs/dev/specs/MIGRATION_PLAN_CONTRACT.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Migration Plan Contract
2+
3+
## Purpose
4+
5+
The Migration Plan contract defines a metadata-only record that decides whether a user-owned library/install record needs migration from a source version to a target Release version.
6+
7+
Migration Plan links an owner to a Project, target Release, Version Compatibility record, Update Channel, Library Item, and Install Receipt. It does not store runtime state, toolState data, installer state, updater implementation details, migration implementation code, file bytes, or download state.
8+
9+
## Ownership
10+
11+
- Every Migration Plan requires `ownerId`.
12+
- `ownerId` is the user whose Library Item and Install Receipt are being evaluated.
13+
- Migration Plan access is owner-private unless platform administration permission applies.
14+
- Migration Plan does not replace Project, Release, Version Compatibility, Update Channel, Library Item, or Install Receipt ownership.
15+
16+
## Required Linkage
17+
18+
Migration Plan requires:
19+
20+
- `projectId`
21+
- `targetRelease`
22+
- `versionCompatibility`
23+
- `updateChannel`
24+
- `libraryItem`
25+
- `installReceipt`
26+
27+
Required consistency:
28+
29+
- `versionCompatibility.ownerId` must match `ownerId`.
30+
- `updateChannel.ownerId` must match `ownerId`.
31+
- `libraryItem.ownerId` must match `ownerId`.
32+
- `installReceipt.ownerId` must match `ownerId`.
33+
- `targetRelease.projectId` must match `projectId`.
34+
- `versionCompatibility.projectId` must match `projectId`.
35+
- `updateChannel.projectId` must match `projectId`.
36+
- `libraryItem.projectId` must match `projectId`.
37+
- `installReceipt.projectId` must match `projectId`.
38+
- `versionCompatibility.releaseId` must match `targetRelease.releaseId`.
39+
- `updateChannel.releaseId` must match `targetRelease.releaseId`.
40+
- `libraryItem.releaseId` must match `targetRelease.releaseId`.
41+
- `installReceipt.releaseId` must match `targetRelease.releaseId`.
42+
- `updateChannel.publishId` must match `versionCompatibility.publishId`.
43+
- `libraryItem.publishId` must match `versionCompatibility.publishId`.
44+
- `installReceipt.publishId` must match `versionCompatibility.publishId`.
45+
- `installReceipt.libraryItemId` must match `libraryItem.libraryItemId`.
46+
47+
## Version Rules
48+
49+
Migration Plan requires:
50+
51+
- `sourceVersion`
52+
- `targetVersion`
53+
- `schemaVersion`
54+
55+
Rules:
56+
57+
- Versions are positive integers.
58+
- `targetVersion` must match `targetRelease.version`.
59+
- `targetVersion` must match `versionCompatibility.targetVersion`.
60+
- `schemaVersion` must match `versionCompatibility.supportedSchemaVersion`.
61+
62+
## Migration States
63+
64+
Allowed migration states:
65+
66+
- `notRequired`
67+
- `required`
68+
- `blocked`
69+
- `completed`
70+
71+
Rules:
72+
73+
- `notRequired` requires `sourceVersion` and `targetVersion` to match.
74+
- `required` requires `targetVersion` to be newer than `sourceVersion`.
75+
- `completed` requires `targetVersion` to be newer than `sourceVersion`.
76+
- `completed` requires `completedAt`.
77+
- If Version Compatibility is `blocked` or `incompatible`, Migration Plan must be `blocked`.
78+
79+
## Fields
80+
81+
- `migrationPlanId`
82+
- `ownerId`
83+
- `projectId`
84+
- `targetRelease`
85+
- `versionCompatibility`
86+
- `updateChannel`
87+
- `libraryItem`
88+
- `installReceipt`
89+
- `sourceVersion`
90+
- `targetVersion`
91+
- `schemaVersion`
92+
- `migrationState`
93+
- `plannedAt`
94+
- `completedAt`
95+
- `migrationNotes`
96+
97+
## Forbidden State
98+
99+
Migration Plan records must not contain:
100+
101+
- runtime state
102+
- toolState data
103+
- installer state
104+
- updater implementation details
105+
- migration implementation code
106+
- file bytes
107+
- download state
108+
109+
Migration Plan records may say that migration is not required, required, blocked, or completed. Migration scripts, executable migration code, updater jobs, installer plans, patch bytes, file content, download grants, and runtime context do not live inside the Migration Plan contract.
110+
111+
## Non-Goals
112+
113+
- No database implementation.
114+
- No authentication implementation.
115+
- No installer implementation.
116+
- No updater implementation.
117+
- No migration implementation.
118+
- No file delivery implementation.
119+
- No download implementation.
120+
- No UI or runtime behavior changes.

0 commit comments

Comments
 (0)