Skip to content

Commit 34567f0

Browse files
ToolboxAidToolboxAid
committed
Add Version Compatibility contract tests and upgrade boundary rules - PR_26152_090-version-compatibility-contract-tests
1 parent ab64ec6 commit 34567f0

5 files changed

Lines changed: 1588 additions & 0 deletions

File tree

‎docs/dev/reports/version_compatibility_contract_tests_validation.md‎

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

‎docs/dev/specs/VERSION_COMPATIBILITY_CONTRACT.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Version Compatibility Contract
2+
3+
## Purpose
4+
5+
The Version Compatibility contract defines a metadata-only record that evaluates whether an installed or library-owned item is compatible with a target Release and Publish record.
6+
7+
Version Compatibility links an owner to a Project, Release, Publish record, Update Channel, Library Item, and Install Receipt. It does not store runtime state, toolState data, installer state, updater implementation details, migration implementation details, file bytes, or download state.
8+
9+
## Ownership
10+
11+
- Every Version Compatibility record requires `ownerId`.
12+
- `ownerId` is the user whose Library Item and Install Receipt are being evaluated.
13+
- Version Compatibility access is owner-private unless platform administration permission applies.
14+
- Version Compatibility does not replace Project, Release, Publish, Update Channel, Library Item, or Install Receipt ownership.
15+
16+
## Required Linkage
17+
18+
Version Compatibility requires:
19+
20+
- `projectId`
21+
- `sourceRelease`
22+
- `sourcePublish`
23+
- `updateChannel`
24+
- `libraryItem`
25+
- `installReceipt`
26+
27+
Required consistency:
28+
29+
- `updateChannel.ownerId` must match `ownerId`.
30+
- `libraryItem.ownerId` must match `ownerId`.
31+
- `installReceipt.ownerId` must match `ownerId`.
32+
- `sourceRelease.projectId` must match `projectId`.
33+
- `sourcePublish.projectId` must match `projectId`.
34+
- `updateChannel.projectId` must match `projectId`.
35+
- `libraryItem.projectId` must match `projectId`.
36+
- `installReceipt.projectId` must match `projectId`.
37+
- `sourcePublish.releaseId` must match `sourceRelease.releaseId`.
38+
- `updateChannel.releaseId` must match `sourceRelease.releaseId`.
39+
- `libraryItem.releaseId` must match `sourceRelease.releaseId`.
40+
- `installReceipt.releaseId` must match `sourceRelease.releaseId`.
41+
- `updateChannel.publishId` must match `sourcePublish.publishId`.
42+
- `libraryItem.publishId` must match `sourcePublish.publishId`.
43+
- `installReceipt.publishId` must match `sourcePublish.publishId`.
44+
- `installReceipt.libraryItemId` must match `libraryItem.libraryItemId`.
45+
46+
## Version Range
47+
48+
Version Compatibility requires:
49+
50+
- `minimumVersion`
51+
- `maximumVersion`
52+
- `targetVersion`
53+
- `supportedSchemaVersion`
54+
55+
Rules:
56+
57+
- Versions are positive integers.
58+
- `minimumVersion` must be less than or equal to `maximumVersion`.
59+
- `targetVersion` must be inside the supported range.
60+
- `targetVersion` must match `sourceRelease.version`.
61+
- `supportedSchemaVersion` records the schema version the compatibility decision was evaluated against.
62+
63+
## Compatibility State
64+
65+
Allowed compatibility states:
66+
67+
- `incompatible`
68+
- `compatible`
69+
- `deprecated`
70+
- `blocked`
71+
72+
Compatibility state describes the evaluation result. It does not authorize migration, installation, update, or download behavior by itself.
73+
74+
## Fields
75+
76+
- `versionCompatibilityId`
77+
- `ownerId`
78+
- `projectId`
79+
- `sourceRelease`
80+
- `sourcePublish`
81+
- `updateChannel`
82+
- `libraryItem`
83+
- `installReceipt`
84+
- `minimumVersion`
85+
- `maximumVersion`
86+
- `targetVersion`
87+
- `supportedSchemaVersion`
88+
- `compatibilityState`
89+
- `evaluatedAt`
90+
- `compatibilityNotes`
91+
92+
## Forbidden State
93+
94+
Version Compatibility records must not contain:
95+
96+
- runtime state
97+
- toolState data
98+
- installer state
99+
- updater implementation details
100+
- migration implementation details
101+
- file bytes
102+
- download state
103+
104+
Compatibility checks may later feed update or migration workflows, but updater jobs, migration scripts, patch bytes, file content, install plans, download grants, and runtime context do not live inside the Version Compatibility contract.
105+
106+
## Non-Goals
107+
108+
- No database implementation.
109+
- No authentication implementation.
110+
- No installer implementation.
111+
- No updater implementation.
112+
- No migration implementation.
113+
- No file delivery implementation.
114+
- No download implementation.
115+
- No UI or runtime behavior changes.

0 commit comments

Comments
 (0)