Audit and deduplicate tool contract structure while preserving per-tool ownership - PR_26152_074-tool-contract-deduplication-audit

Author: ToolboxAid

docs/dev/reports/tool_contract_coverage.md

@@ -1,6 +1,6 @@
 # Tool Contract Coverage
 
-PR: PR_26152_073-split-tool-contracts-by-tool
+PR: PR_26152_074-tool-contract-deduplication-audit
 Date: 2026-06-02
 
 ## Discovery Sources
@@ -12,6 +12,14 @@ Date: 2026-06-02
 - Per-tool contracts: `src/shared/contracts/tools/*ToolContract.js`
 - Contract index: `src/shared/contracts/tools/toolContractsIndex.js`
 
+## Deduplication Status
+
+- Per-tool modules remain split: 34/34 retained.
+- Matching per-tool tests remain split: 34/34 retained.
+- Shared primitives now own repeated empty/all supported asset declarations and draft contract creation.
+- Per-tool declarations still own only tool-specific ids, types, inputs, outputs, asset support, imports, and exports.
+- Registered first-class tool coverage remains unchanged.
+
 ## Active Registered First-Class Tools
 
 All active visible registered first-class tools discovered through `getVisibleActiveToolRegistry()` have matching contracts.
@@ -76,3 +84,6 @@ The root Tools Index card data includes public/root cards that are not all activ
 - Registered first-class tools without contract: 0
 - Root Tools Index cards reviewed: 18
 - Root Tools Index cards skipped as non-tool surfaces: 2
+- Duplicated empty supported asset declarations remaining in tool files: 0
+- Duplicated all-supported-assets declarations remaining in tool files: 0
+- Duplicated draft status declarations remaining in tool files: 0

docs/dev/reports/tool_contract_deduplication_audit.md

@@ -0,0 +1,105 @@
+# Tool Contract Deduplication Audit
+
+PR: PR_26152_074-tool-contract-deduplication-audit
+Date: 2026-06-02
+
+## Scope
+
+- Audited current contract structure after PR_26152_073 split tool contracts by tool.
+- Limited changes to `src/shared/contracts/`, `src/shared/contracts/tools/`, contract tests validation, and reports.
+- No runtime code, UI, CSS, HTML, or non-contract JavaScript changed.
+- Per-tool contract files remain split and were not merged into one file.
+
+## Structure Reviewed
+
+| Area | Result |
+|---|---|
+| `identityPermissionsContract.js` | Identity roles, permissions, scopes, and visibility states remain shared primitives. |
+| `projectContract.js` | Project roles, visibility, access rules, and state validation remain shared primitives. |
+| `toolStateContract.js` | Tool State ownership, visibility, status, versioning, recovery, and exportability remain shared primitives. |
+| `assetContract.js` | Generic asset ownership, status, visibility, metadata, type, and export behavior remain shared primitives. |
+| `paletteContract.js` | Palette-specific swatch validation and portable export behavior remain shared primitives. |
+| `vectorAssetContract.js` | Vector asset validation and portable export behavior remain shared primitives. |
+| `toolContractPrimitives.js` | Owns tool contract defaults, validation, ownership, visibility, access, export/import format validation, and shared asset-type/status declaration helpers. |
+| `contracts/tools/*.js` | Remain per-tool declarations only, with unique tool inputs/outputs/type/assets/import/export data. |
+
+## Duplication Findings
+
+| Category | Before | After | Action |
+|---|---:|---:|---|
+| Per-tool contract files | 34 | 34 | Preserved split per-tool modules. |
+| Matching per-tool tests | 34 | 34 | Preserved tool-by-tool coverage. |
+| `supportedAssetTypes: []` duplicated in tool files | 13 | 0 | Replaced with `TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE`. |
+| `Object.values(ASSET_TYPES)` duplicated in tool files | 5 | 0 | Replaced with `TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL`. |
+| `status: TOOL_CONTRACT_STATUS.DRAFT` duplicated in tool files | 11 | 0 | Replaced with `createDraftToolContract(...)`. |
+| Duplicated ownership rules in tool files | 0 | 0 | Ownership remains in `createToolContract`. |
+| Duplicated visibility rules in tool files | 0 | 0 | Visibility/access remains in `toolContractPrimitives.js`. |
+| Duplicated validation logic in tool files | 0 | 0 | Validation remains in `validateToolContract` and shared test helper. |
+| Duplicated portable export/import validation | 0 | 0 | Portable export/import validation remains in `toolContractPrimitives.js`. |
+
+## Per-Tool Audit
+
+| Tool Contract Group | Unique Tool Data | Deduplicated Data | Validation/Ownership/Visibility |
+|---|---|---|---|
+| Active registered tools | `toolId`, `toolType`, inputs, outputs, asset types, import/export formats | Empty/all supported asset declarations where applicable | Shared through `toolContractPrimitives.js`. |
+| Root Tools Index planning contracts | `toolId`, `toolType`, inputs, outputs, asset types, import/export formats | Draft status, empty/all supported asset declarations where applicable | Shared through `toolContractPrimitives.js`. |
+| Tool contract index | Contract aggregation and root-card coverage mapping | No validation logic added | Lookup and coverage only; per-tool declarations stay split. |
+| Per-tool tests | Expected tool id per module | Repeated assertions remain in `toolContractTestHelpers.mjs` | Matching one test per tool preserved. |
+
+## Shared Primitive Ownership Summary
+
+`src/shared/contracts/toolContractPrimitives.js` now owns:
+
+- default tool contract owner/project identifiers
+- default visibility/status/version behavior
+- `createToolContract`
+- `createDraftToolContract`
+- `TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL`
+- `TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE`
+- tool type/status/visibility/format validators
+- source tool state validation
+- actor visibility/access checks
+- archived edit policy checks
+- portable tool contract export creation and validation
+
+Per-tool contract modules own only the data that distinguishes that tool:
+
+- `toolId`
+- `toolType`
+- `requiredInputs`
+- `producedOutputs`
+- `supportedAssetTypes`
+- `importFormats`
+- `exportFormats`
+
+## Behavior Invariance
+
+- No tool contract was removed.
+- No tool contract id changed.
+- No per-tool coverage test was removed.
+- No validation, ownership, visibility, access, status, import, or export rule changed.
+- All changed contract outputs remain covered by the same targeted contract test suite.
+
+## Validation
+
+```powershell
+$rootContractTests = Get-ChildItem -Path tests/shared -Filter '*Contract.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName }
+$toolContractTests = Get-ChildItem -Path tests/shared/tools -Filter '*.test.mjs' | Sort-Object Name | ForEach-Object { $_.FullName }
+node ./scripts/run-node-test-files.mjs $rootContractTests $toolContractTests
+```
+
+Result: PASS, 41/41 targeted node test files passed.
+
+## Lane Report
+
+- Lanes executed: contract lane for shared contracts and tool contract declarations.
+- Lanes skipped: runtime, integration, engine, samples, recovery/UAT because this PR changes only contract declarations/primitives and reports.
+- Samples decision: SKIP because samples are out of scope and no sample JSON or runtime behavior changed.
+- Playwright impacted: No. This PR changes contract primitives/declarations only and does not change browser UI or runtime behavior.
+- Blocker scope: targeted contract lane only.
+
+## Manual Validation
+
+- Confirm `src/shared/contracts/tools/` still contains one contract module per tool/control.
+- Confirm `tests/shared/tools/` still contains one matching test per tool/control plus shared coverage/helper tests.
+- Confirm no runtime, UI, CSS, HTML, samples, games, or non-contract tool files changed.

src/shared/contracts/toolContractPrimitives.js

@@ -22,6 +22,7 @@ import {
   isToolStateVersion,
 } from "./toolStateContract.js";
 import {
+  ASSET_TYPES,
   isAssetType,
 } from "./assetContract.js";
 
@@ -199,6 +200,11 @@ export const TOOL_CONTRACT_ERRORS = Object.freeze({
   PORTABLE_EXPORT_INVALID: "TOOL_CONTRACT_PORTABLE_EXPORT_INVALID",
 });
 
+export const TOOL_CONTRACT_SUPPORTED_ASSET_TYPES = Object.freeze({
+  ALL: Object.freeze(Object.values(ASSET_TYPES)),
+  NONE: Object.freeze([]),
+});
+
 export function createToolContract({
   toolId,
   toolType,
@@ -228,6 +234,13 @@ export function createToolContract({
   });
 }
 
+export function createDraftToolContract(toolContractDeclaration) {
+  return createToolContract({
+    ...toolContractDeclaration,
+    status: TOOL_CONTRACT_STATUS.DRAFT,
+  });
+}
+
 export function createRootCardCoverage(title, contractId, status, reason) {
   return Object.freeze({ title, contractId, status, reason });
 }

src/shared/contracts/tools/aiAssistantToolContract.js

@@ -6,18 +6,17 @@ aiAssistantToolContract.js
 */
 import {
   TOOL_CONTRACT_FORMATS,
-  TOOL_CONTRACT_STATUS,
+  TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
-  createToolContract,
+  createDraftToolContract,
 } from "../toolContractPrimitives.js";
 
-export const AI_ASSISTANT_TOOL_CONTRACT = createToolContract({
+export const AI_ASSISTANT_TOOL_CONTRACT = createDraftToolContract({
   toolId: "ai-assistant",
   toolType: TOOL_CONTRACT_TYPES.UTILITY,
   requiredInputs: [TOOL_CONTRACT_FORMATS.TEXT],
   producedOutputs: [TOOL_CONTRACT_FORMATS.TEXT],
-  supportedAssetTypes: [],
+  supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE,
   importFormats: [TOOL_CONTRACT_FORMATS.TEXT],
   exportFormats: [TOOL_CONTRACT_FORMATS.TEXT],
-  status: TOOL_CONTRACT_STATUS.DRAFT,
 });

src/shared/contracts/tools/animationStudioToolContract.js

@@ -9,18 +9,16 @@ import {
 } from "../assetContract.js";
 import {
   TOOL_CONTRACT_FORMATS,
-  TOOL_CONTRACT_STATUS,
   TOOL_CONTRACT_TYPES,
-  createToolContract,
+  createDraftToolContract,
 } from "../toolContractPrimitives.js";
 
-export const ANIMATION_STUDIO_TOOL_CONTRACT = createToolContract({
+export const ANIMATION_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "animation-studio",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
   requiredInputs: [TOOL_CONTRACT_FORMATS.IMAGE_FILE],
   producedOutputs: [TOOL_CONTRACT_FORMATS.ANIMATION_JSON],
   supportedAssetTypes: [ASSET_TYPES.IMAGE],
   importFormats: [TOOL_CONTRACT_FORMATS.IMAGE_FILE],
   exportFormats: [TOOL_CONTRACT_FORMATS.ANIMATION_JSON],
-  status: TOOL_CONTRACT_STATUS.DRAFT,
 });

src/shared/contracts/tools/assetManagerV2ToolContract.js

@@ -4,11 +4,9 @@ David Quesenberry
 06/02/2026
 assetManagerV2ToolContract.js
 */
-import {
-  ASSET_TYPES,
-} from "../assetContract.js";
 import {
   TOOL_CONTRACT_FORMATS,
+  TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createToolContract,
 } from "../toolContractPrimitives.js";
@@ -18,7 +16,7 @@ export const ASSET_MANAGER_V2_TOOL_CONTRACT = createToolContract({
   toolType: TOOL_CONTRACT_TYPES.MANAGER,
   requiredInputs: [TOOL_CONTRACT_FORMATS.PALETTE_JSON, TOOL_CONTRACT_FORMATS.METADATA_JSON],
   producedOutputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
-  supportedAssetTypes: Object.values(ASSET_TYPES),
+  supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL,
   importFormats: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   exportFormats: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
 });

src/shared/contracts/tools/assetPipelineToolContract.js

@@ -4,11 +4,9 @@ David Quesenberry
 06/02/2026
 assetPipelineToolContract.js
 */
-import {
-  ASSET_TYPES,
-} from "../assetContract.js";
 import {
   TOOL_CONTRACT_FORMATS,
+  TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
   createToolContract,
 } from "../toolContractPrimitives.js";
@@ -18,7 +16,7 @@ export const ASSET_PIPELINE_TOOL_CONTRACT = createToolContract({
   toolType: TOOL_CONTRACT_TYPES.PIPELINE,
   requiredInputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   producedOutputs: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
-  supportedAssetTypes: Object.values(ASSET_TYPES),
+  supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL,
   importFormats: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   exportFormats: [TOOL_CONTRACT_FORMATS.METADATA_JSON, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
 });

src/shared/contracts/tools/assetStudioToolContract.js

@@ -9,18 +9,16 @@ import {
 } from "../assetContract.js";
 import {
   TOOL_CONTRACT_FORMATS,
-  TOOL_CONTRACT_STATUS,
   TOOL_CONTRACT_TYPES,
-  createToolContract,
+  createDraftToolContract,
 } from "../toolContractPrimitives.js";
 
-export const ASSET_STUDIO_TOOL_CONTRACT = createToolContract({
+export const ASSET_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "asset-studio",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
   requiredInputs: [TOOL_CONTRACT_FORMATS.PALETTE_JSON],
   producedOutputs: [TOOL_CONTRACT_FORMATS.IMAGE_FILE, TOOL_CONTRACT_FORMATS.VECTOR_JSON, TOOL_CONTRACT_FORMATS.PALETTE_JSON],
   supportedAssetTypes: [ASSET_TYPES.IMAGE, ASSET_TYPES.VECTOR, ASSET_TYPES.PALETTE],
   importFormats: [TOOL_CONTRACT_FORMATS.PALETTE_JSON, TOOL_CONTRACT_FORMATS.IMAGE_FILE],
   exportFormats: [TOOL_CONTRACT_FORMATS.IMAGE_FILE, TOOL_CONTRACT_FORMATS.VECTOR_JSON, TOOL_CONTRACT_FORMATS.PALETTE_JSON],
-  status: TOOL_CONTRACT_STATUS.DRAFT,
 });

src/shared/contracts/tools/codeStudioToolContract.js

@@ -6,18 +6,17 @@ codeStudioToolContract.js
 */
 import {
   TOOL_CONTRACT_FORMATS,
-  TOOL_CONTRACT_STATUS,
+  TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
-  createToolContract,
+  createDraftToolContract,
 } from "../toolContractPrimitives.js";
 
-export const CODE_STUDIO_TOOL_CONTRACT = createToolContract({
+export const CODE_STUDIO_TOOL_CONTRACT = createDraftToolContract({
   toolId: "code-studio",
   toolType: TOOL_CONTRACT_TYPES.EDITOR,
   requiredInputs: [TOOL_CONTRACT_FORMATS.CODE_FILE],
   producedOutputs: [TOOL_CONTRACT_FORMATS.CODE_FILE],
-  supportedAssetTypes: [],
+  supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.NONE,
   importFormats: [TOOL_CONTRACT_FORMATS.CODE_FILE],
   exportFormats: [TOOL_CONTRACT_FORMATS.CODE_FILE],
-  status: TOOL_CONTRACT_STATUS.DRAFT,
 });

src/shared/contracts/tools/gameBuilderToolContract.js

@@ -4,23 +4,19 @@ David Quesenberry
 06/02/2026
 gameBuilderToolContract.js
 */
-import {
-  ASSET_TYPES,
-} from "../assetContract.js";
 import {
   TOOL_CONTRACT_FORMATS,
-  TOOL_CONTRACT_STATUS,
+  TOOL_CONTRACT_SUPPORTED_ASSET_TYPES,
   TOOL_CONTRACT_TYPES,
-  createToolContract,
+  createDraftToolContract,
 } from "../toolContractPrimitives.js";
 
-export const GAME_BUILDER_TOOL_CONTRACT = createToolContract({
+export const GAME_BUILDER_TOOL_CONTRACT = createDraftToolContract({
   toolId: "game-builder",
   toolType: TOOL_CONTRACT_TYPES.STUDIO,
   requiredInputs: [TOOL_CONTRACT_FORMATS.GAME_DESIGN_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   producedOutputs: [TOOL_CONTRACT_FORMATS.GAME_MANIFEST],
-  supportedAssetTypes: Object.values(ASSET_TYPES),
+  supportedAssetTypes: TOOL_CONTRACT_SUPPORTED_ASSET_TYPES.ALL,
   importFormats: [TOOL_CONTRACT_FORMATS.GAME_DESIGN_JSON, TOOL_CONTRACT_FORMATS.ASSET],
   exportFormats: [TOOL_CONTRACT_FORMATS.GAME_MANIFEST, TOOL_CONTRACT_FORMATS.PROJECT_PACKAGE],
-  status: TOOL_CONTRACT_STATUS.DRAFT,
 });