|
| 1 | +# Unified Tool Contract Behavior Validation |
| 2 | + |
| 3 | +PR: PR_26152_075-unify-tool-contract-behavior |
| 4 | +Date: 2026-06-02 |
| 5 | + |
| 6 | +## Scope |
| 7 | + |
| 8 | +- Limited changes to shared contracts, per-tool contract declarations, contract tests, and reports. |
| 9 | +- No runtime code, UI, CSS, HTML, samples, games, or non-contract tool files changed. |
| 10 | +- Corrected the shared behavior surface to `src/shared/contracts/toolContract.js`. |
| 11 | +- Kept per-tool declarations split under `src/shared/contracts/tools/`. |
| 12 | + |
| 13 | +## Structure |
| 14 | + |
| 15 | +| Required Area | Implemented Surface | Status | |
| 16 | +|---|---|---| |
| 17 | +| `contracts/toolContract.*` shared tool behavior | `src/shared/contracts/toolContract.js` | PASS | |
| 18 | +| `contracts/tools/<toolName>Contract.*` declarations | `src/shared/contracts/tools/*Contract.js` | PASS | |
| 19 | +| Platform object contracts | `identityPermissionsContract.js`, `projectContract.js`, `toolStateContract.js`, `assetContract.js`, `paletteContract.js`, `vectorAssetContract.js` | PASS | |
| 20 | +| Tool behavior tests | `tests/shared/tools/ToolContractCoverage.test.mjs` | PASS | |
| 21 | +| Per-tool declaration tests | `tests/shared/tools/*ToolContract.test.mjs` through `toolContractTestHelpers.mjs` | PASS | |
| 22 | + |
| 23 | +## Behavior Model |
| 24 | + |
| 25 | +`src/shared/contracts/toolContract.js` owns the shared behavior model: |
| 26 | + |
| 27 | +- owner and project defaults |
| 28 | +- visibility, status, and version rules |
| 29 | +- import/export format rules |
| 30 | +- produced output rules |
| 31 | +- supported asset type rules |
| 32 | +- source tool state rules |
| 33 | +- archive edit policy checks |
| 34 | +- actor visibility and permission checks |
| 35 | +- portable export validation |
| 36 | + |
| 37 | +`src/shared/contracts/tools/*Contract.js` owns only tool-specific declarations: |
| 38 | + |
| 39 | +- `toolId` |
| 40 | +- `toolType` |
| 41 | +- `requiredInputs` |
| 42 | +- `producedOutputs` |
| 43 | +- `supportedAssetTypes` |
| 44 | +- `importFormats` |
| 45 | +- `exportFormats` |
| 46 | +- tool-specific metadata only |
| 47 | + |
| 48 | +## Naming Cleanup |
| 49 | + |
| 50 | +- Renamed shared behavior file from `toolContractPrimitives.js` to `toolContract.js`. |
| 51 | +- Renamed per-tool declaration files from `*ToolContract.js` to `*Contract.js`. |
| 52 | +- No `src/shared/contracts/tools/paletteContract.*` file exists. |
| 53 | +- The platform Palette object contract remains `src/shared/contracts/paletteContract.js`. |
| 54 | +- The Palette Manager tool declaration is `src/shared/contracts/tools/paletteManagerV2Contract.js`. |
| 55 | +- No object contract was duplicated under `src/shared/contracts/tools/`. |
| 56 | + |
| 57 | +## Test Model |
| 58 | + |
| 59 | +- Shared behavior is validated once through `ToolContractCoverage.test.mjs`. |
| 60 | +- Per-tool tests now validate declaration identity and declaration shape only. |
| 61 | +- Ownership, project, visibility, permission, archive, and portable export behavior are not duplicated in every per-tool test. |
| 62 | + |
| 63 | +## Validation Commands |
| 64 | + |
| 65 | +```powershell |
| 66 | +$rootContractTests = Get-ChildItem -Path tests/shared -Filter '*Contract.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName } |
| 67 | +$toolContractTests = Get-ChildItem -Path tests/shared/tools -Filter '*.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName } |
| 68 | +node ./scripts/run-node-test-files.mjs $rootContractTests $toolContractTests |
| 69 | +``` |
| 70 | + |
| 71 | +Result: PASS, 41/41 targeted node test files passed. |
| 72 | + |
| 73 | +## Additional Checks |
| 74 | + |
| 75 | +```powershell |
| 76 | +rg "toolContractPrimitives|ToolContract\.js|ToolContract.js|supportedAssetTypes: \[\]|TOOL_CONTRACT_STATUS\.DRAFT|Object\.values\(ASSET_TYPES\)" -n src/shared/contracts tests/shared docs/dev/reports |
| 77 | +``` |
| 78 | + |
| 79 | +Result: PASS for source/test scope. Historical reports may mention older PR filenames, but current required reports reference the unified structure. |
| 80 | + |
| 81 | +```powershell |
| 82 | +git diff --name-only -- '*.css' '*.html' |
| 83 | +``` |
| 84 | + |
| 85 | +Result: PASS, no CSS or HTML files changed. |
| 86 | + |
| 87 | +## Coverage |
| 88 | + |
| 89 | +- Active visible registered first-class tools covered: 23/23. |
| 90 | +- Tool declarations covered: 34/34. |
| 91 | +- Matching per-tool declaration tests retained: 34/34. |
| 92 | +- Root Tools Index cards reviewed: 18. |
| 93 | +- Non-tool Tools Index cards documented as skipped: 2 (`Marketplace`, `Arcade`). |
| 94 | + |
| 95 | +## Lane Report |
| 96 | + |
| 97 | +- Lanes executed: contract lane for shared tool behavior, platform object separation, and per-tool declarations. |
| 98 | +- Lanes skipped: runtime, integration, engine, samples, recovery/UAT because no runtime, handoff, engine, sample, UI, CSS, or HTML behavior changed. |
| 99 | +- Samples decision: SKIP because samples are out of scope and no sample JSON/runtime behavior changed. |
| 100 | +- Playwright impacted: No. This PR changes contract module naming/structure and tests only. |
| 101 | +- Blocker scope: targeted contract lane only. |
| 102 | + |
| 103 | +## Expected Behavior |
| 104 | + |
| 105 | +- PASS when the shared behavior model validates all tool contracts once, per-tool declaration tests remain present, and registered tool coverage remains complete. |
| 106 | +- WARN only for historical PR reports that describe earlier filenames from PR_26152_073 or PR_26152_074. |
0 commit comments