Skip to content

Commit 857e2a7

Browse files
qbytesdq-jpgqbytesdq-jpg
committed
Unify tool contract behavior and keep per-tool contracts as thin declarations - PR_26152_075-unify-tool-contract-behavior
1 parent 1985b67 commit 857e2a7

74 files changed

Lines changed: 299 additions & 228 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dev/reports/tool_contract_coverage.md‎

Lines changed: 46 additions & 46 deletions
Large diffs are not rendered by default.

‎docs/dev/reports/unified_tool_contract_behavior_validation.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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.

src/shared/contracts/toolContractPrimitives.js renamed to src/shared/contracts/toolContract.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
toolContractPrimitives.js
5+
toolContract.js
66
*/
77
import {
88
IDENTITY_PERMISSION_SCOPES,

src/shared/contracts/tools/aiAssistantToolContract.js renamed to src/shared/contracts/tools/aiAssistantContract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
aiAssistantToolContract.js
5+
aiAssistantContract.js
66
*/
77
import {
88
TOOL_CONTRACT_FORMATS,
99
TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
1010
TOOL_CONTRACT_TYPES,
1111
createDraftToolContract,
12-
} from "../toolContractPrimitives.js";
12+
} from "../toolContract.js";
1313

1414
export const AI_ASSISTANT_TOOL_CONTRACT = createDraftToolContract({
1515
toolId: "ai-assistant",

src/shared/contracts/tools/animationStudioToolContract.js renamed to src/shared/contracts/tools/animationStudioContract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
animationStudioToolContract.js
5+
animationStudioContract.js
66
*/
77
import {
88
ASSET_TYPES,
@@ -11,7 +11,7 @@ import {
1111
TOOL_CONTRACT_FORMATS,
1212
TOOL_CONTRACT_TYPES,
1313
createDraftToolContract,
14-
} from "../toolContractPrimitives.js";
14+
} from "../toolContract.js";
1515

1616
export const ANIMATION_STUDIO_TOOL_CONTRACT = createDraftToolContract({
1717
toolId: "animation-studio",

src/shared/contracts/tools/assetManagerV2ToolContract.js renamed to src/shared/contracts/tools/assetManagerV2Contract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
assetManagerV2ToolContract.js
5+
assetManagerV2Contract.js
66
*/
77
import {
88
TOOL_CONTRACT_FORMATS,
99
TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
1010
TOOL_CONTRACT_TYPES,
1111
createToolContract,
12-
} from "../toolContractPrimitives.js";
12+
} from "../toolContract.js";
1313

1414
export const ASSET_MANAGER_V2_TOOL_CONTRACT = createToolContract({
1515
toolId: "asset-manager-v2",

src/shared/contracts/tools/assetPipelineToolContract.js renamed to src/shared/contracts/tools/assetPipelineContract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
assetPipelineToolContract.js
5+
assetPipelineContract.js
66
*/
77
import {
88
TOOL_CONTRACT_FORMATS,
99
TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
1010
TOOL_CONTRACT_TYPES,
1111
createToolContract,
12-
} from "../toolContractPrimitives.js";
12+
} from "../toolContract.js";
1313

1414
export const ASSET_PIPELINE_TOOL_CONTRACT = createToolContract({
1515
toolId: "asset-pipeline",

src/shared/contracts/tools/assetStudioToolContract.js renamed to src/shared/contracts/tools/assetStudioContract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
assetStudioToolContract.js
5+
assetStudioContract.js
66
*/
77
import {
88
ASSET_TYPES,
@@ -11,7 +11,7 @@ import {
1111
TOOL_CONTRACT_FORMATS,
1212
TOOL_CONTRACT_TYPES,
1313
createDraftToolContract,
14-
} from "../toolContractPrimitives.js";
14+
} from "../toolContract.js";
1515

1616
export const ASSET_STUDIO_TOOL_CONTRACT = createDraftToolContract({
1717
toolId: "asset-studio",

src/shared/contracts/tools/audioSfxPlaygroundV2ToolContract.js renamed to src/shared/contracts/tools/audioSfxPlaygroundV2Contract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
audioSfxPlaygroundV2ToolContract.js
5+
audioSfxPlaygroundV2Contract.js
66
*/
77
import {
88
ASSET_TYPES,
@@ -11,7 +11,7 @@ import {
1111
TOOL_CONTRACT_FORMATS,
1212
TOOL_CONTRACT_TYPES,
1313
createToolContract,
14-
} from "../toolContractPrimitives.js";
14+
} from "../toolContract.js";
1515

1616
export const AUDIO_SFX_PLAYGROUND_V2_TOOL_CONTRACT = createToolContract({
1717
toolId: "audio-sfx-playground-v2",

src/shared/contracts/tools/codeStudioToolContract.js renamed to src/shared/contracts/tools/codeStudioContract.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,14 @@
22
Toolbox Aid
33
David Quesenberry
44
06/02/2026
5-
codeStudioToolContract.js
5+
codeStudioContract.js
66
*/
77
import {
88
TOOL_CONTRACT_FORMATS,
99
TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
1010
TOOL_CONTRACT_TYPES,
1111
createDraftToolContract,
12-
} from "../toolContractPrimitives.js";
12+
} from "../toolContract.js";
1313

1414
export const CODE_STUDIO_TOOL_CONTRACT = createDraftToolContract({
1515
toolId: "code-studio",

0 commit comments

Comments
 (0)