Enforce explicit tool input contract (payload + optional palette only) - PR 11.132

Author: DavidQ

docs/dev/codex_commands.md

@@ -10,18 +10,18 @@ ALLOWED FILES:
 
 TASK:
 
-1. Find palette usage
-2. Remove:
-   - palette injection
-   - palette merging
-   - defaults
-3. Ensure separate pass-through
+1. Find tool launch calls
+2. Enforce signature:
+   launch(toolId, payloadJson, paletteJson?)
+
+3. Remove:
+   - implicit/global input
+   - hidden dependencies
 
 VERIFY:
-payload unchanged
-palette unchanged
+- inputs are explicit only
 
 REPORT:
-docs/dev/reports/palette_pass_through_11_131.txt
+docs/dev/reports/final_tool_input_contract_11_132.txt
 
-FAIL if mutation exists
+FAIL if ambiguity remains

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Enforce palette pass-through routing without mutation - PR 11.131
+Enforce explicit tool input contract (payload + optional palette only) - PR 11.132

docs/dev/reports/final_tool_input_contract_11_132.txt

@@ -0,0 +1,55 @@
+Final Tool Input Contract Report: 11_132
+Date: 2026-04-30
+Repo: C:/Users/davidq/Documents/GitHub/HTML-JavaScript-Gaming
+Mode: STRICT SCOPE
+
+Objective
+- Enforce explicit launch signature at routing boundary:
+  launch(toolId, payloadJson, paletteJson?)
+- Remove implicit/global launch inputs and hidden dependencies.
+
+Routing files changed
+- tools/shared/toolHostRuntime.js
+- tools/Workspace Manager/main.js
+
+Changes
+1) Tool launch API contract
+- Replaced host runtime launch entrypoint with explicit signature:
+  function launch(toolId, payloadJson, paletteJson = null)
+- Removed mount-style config launch API and implicit config forwarding.
+
+2) Explicit-only input enforcement
+- Runtime now blocks launch when payloadJson is missing/non-object.
+- Runtime now blocks launch when paletteJson is provided but not an object.
+
+3) Hidden/implicit input removal
+- Removed launch URL query forwarding from runtime launch path.
+- Removed Workspace Manager forwarded-input reader used for implicit launch params.
+- Workspace Manager now resolves payloadJson explicitly from workspace manifest tool entries.
+- Workspace Manager passes paletteJson explicitly from workspace manifest palette entry when present.
+- Workspace Manager blocks launch when explicit payloadJson is unavailable.
+
+Verification
+A) Syntax/parse
+- node --check tools/shared/toolHostRuntime.js: PASS
+- node --check tools/Workspace Manager/main.js: PASS
+
+B) Signature and call path checks
+- toolHostRuntime has launch signature:
+  function launch(toolId, payloadJson, paletteJson = null): PASS
+- toolHostRuntime no mountTool API remains: PASS
+- Workspace Manager calls runtime.launch(toolId, payloadJson, paletteJson): PASS
+
+C) Explicit-only guards
+- Runtime payloadJson object guard present: PASS
+- Runtime optional paletteJson object guard present: PASS
+- Workspace explicit payload block when absent present: PASS
+- readForwardedToolLaunchParams function removed: PASS
+
+D) Ambiguity check
+- Implicit launch params forwarding removed from active launch path: PASS
+- Launch inputs are explicit-only at routing boundary: PASS
+
+Result
+- PASS
+- No remaining launch-input ambiguity in the updated routing path.

docs/pr/BUILD_PR_LEVEL_11_132_FINAL_TOOL_INPUT_ENFORCEMENT.md

@@ -0,0 +1,57 @@
+# BUILD_PR_LEVEL_11_132_FINAL_TOOL_INPUT_ENFORCEMENT
+
+## Purpose
+Lock the final rule: every tool receives ONLY its JSON payload (+ optional palette as separate JSON), with zero ambiguity.
+
+## STRICT SCOPE
+
+ALLOWED FILES:
+- routing files
+- tool launch handlers
+
+ALLOWED CHANGES:
+- remove ANY remaining multi-input ambiguity
+- enforce explicit parameter passing
+
+## FINAL CONTRACT
+
+Tool launch MUST be:
+
+launch(toolId, payloadJson, paletteJson?)
+
+NOT:
+- launch(toolId, anythingElse)
+- launch(toolId, wrapper)
+- launch(toolId, parentJson)
+
+## REQUIRED CHANGES
+
+1. Ensure function signatures reflect:
+   payload + optional palette
+
+2. Remove:
+   - implicit context passing
+   - global/shared state reads
+   - indirect lookup
+
+3. Ensure:
+   - payloadJson is exact file content
+   - paletteJson is exact file content
+
+## VALIDATION
+
+- trace launch call
+- confirm ONLY payload + palette passed
+
+## REPORT
+
+docs/dev/reports/final_tool_input_contract_11_132.txt:
+- tools checked
+- call signatures
+- violations fixed
+
+## FAILURE
+
+FAIL if:
+- any tool still reads from external/global state
+- any implicit input exists

tools/Workspace Manager/main.js

@@ -697,16 +697,21 @@ async function readWorkspaceManifestToolDiagnosticsFromSamplePreset(samplePreset
             reason: `fetch-failed(status=${response.status})`
           }
         ],
-        schemaContractError: schemaContract?.schemaContractError || ""
+        schemaContractError: schemaContract?.schemaContractError || "",
+        explicitToolPayloadById: new Map(),
+        explicitPalettePayload: null
       };
     }
     const rawSource = await response.json();
     const classifications = classifyWorkspaceManifestTools(rawSource, schemaContract);
+    const explicitInputs = extractWorkspaceManifestExplicitLaunchInputs(rawSource);
     return {
       sourcePath: normalizedPath,
       ...classifications,
       visibleToolIds: [],
-      schemaContractError: schemaContract?.schemaContractError || ""
+      schemaContractError: schemaContract?.schemaContractError || "",
+      explicitToolPayloadById: explicitInputs.explicitToolPayloadById,
+      explicitPalettePayload: explicitInputs.explicitPalettePayload
     };
   } catch (error) {
     return {
@@ -723,9 +728,49 @@ async function readWorkspaceManifestToolDiagnosticsFromSamplePreset(samplePreset
           key: "",
           reason: `fetch-error(${error instanceof Error ? error.message : "unknown"})`
         }
-      ]
+      ],
+      explicitToolPayloadById: new Map(),
+      explicitPalettePayload: null
+    };
+  }
+}
+
+function extractWorkspaceManifestExplicitLaunchInputs(rawSource) {
+  const explicitToolPayloadById = new Map();
+  let explicitPalettePayload = null;
+  if (!isWorkspaceManifestSource(rawSource)) {
+    return {
+      explicitToolPayloadById,
+      explicitPalettePayload
+    };
+  }
+  const toolsBlock = rawSource.tools && typeof rawSource.tools === "object" && !Array.isArray(rawSource.tools)
+    ? rawSource.tools
+    : null;
+  if (!toolsBlock) {
+    return {
+      explicitToolPayloadById,
+      explicitPalettePayload
     };
   }
+
+  Object.entries(toolsBlock).forEach(([rawToolKey, rawToolPayload]) => {
+    const toolId = normalizeTextParam(rawToolKey).toLowerCase();
+    if (!toolId || !rawToolPayload || typeof rawToolPayload !== "object" || Array.isArray(rawToolPayload)) {
+      return;
+    }
+    explicitToolPayloadById.set(toolId, rawToolPayload);
+    if (toolId === "palette-browser"
+      && rawToolPayload.schema === "html-js-gaming.palette"
+      && Array.isArray(rawToolPayload.swatches)) {
+      explicitPalettePayload = rawToolPayload;
+    }
+  });
+
+  return {
+    explicitToolPayloadById,
+    explicitPalettePayload
+  };
 }
 
 function logWorkspaceManifestToolDiagnostics(diagnostics) {
@@ -746,48 +791,6 @@ function logWorkspaceManifestToolDiagnostics(diagnostics) {
   }
 }
 
-function readForwardedToolLaunchParams() {
-  const searchParams = new URL(window.location.href).searchParams;
-  const forwarded = {};
-  const sampleId = normalizeTextParam(searchParams.get("sampleId"));
-  const sampleTitle = normalizeTextParam(searchParams.get("sampleTitle"));
-  const samplePresetPath = normalizeLocalHrefParam(
-    searchParams.get("samplePresetPath"),
-    TOOL_LAUNCH_PARAM_PREFIXES.samplePresetPath
-  );
-  const gameId = normalizeTextParam(searchParams.get("gameId"));
-  const gameTitle = normalizeTextParam(searchParams.get("gameTitle"));
-  const gameHref = normalizeLocalHrefParam(searchParams.get("gameHref"), TOOL_LAUNCH_PARAM_PREFIXES.gameHref);
-  const workspaceHref = normalizeLocalHrefParam(searchParams.get("workspaceHref"), TOOL_LAUNCH_PARAM_PREFIXES.workspaceHref);
-  const returnTo = normalizeLocalHrefParam(searchParams.get("returnTo"), TOOL_LAUNCH_PARAM_PREFIXES.returnTo);
-
-  if (sampleId) {
-    forwarded.sampleId = sampleId;
-  }
-  if (sampleTitle) {
-    forwarded.sampleTitle = sampleTitle;
-  }
-  if (samplePresetPath) {
-    forwarded.samplePresetPath = samplePresetPath;
-  }
-  if (gameId) {
-    forwarded.gameId = gameId;
-  }
-  if (gameTitle) {
-    forwarded.gameTitle = gameTitle;
-  }
-  if (gameHref) {
-    forwarded.gameHref = gameHref;
-  }
-  if (workspaceHref) {
-    forwarded.workspaceHref = workspaceHref;
-  }
-  if (returnTo) {
-    forwarded.returnTo = returnTo;
-  }
-  return forwarded;
-}
-
 function readSelectedToolId() {
   return selectedToolId;
 }
@@ -1225,38 +1228,29 @@ function mountSelectedTool(source = "manual") {
     );
     return false;
   }
-  let optionalState = null;
-  if (refs.stateInput instanceof HTMLTextAreaElement) {
-    const rawState = refs.stateInput.value.trim();
-    if (rawState) {
-      try {
-        optionalState = JSON.parse(rawState);
-      } catch {
-        writeStatus("State JSON is invalid. Fix JSON or clear the state field.");
-        renderMountDiagnostic(
-          "Tool mount blocked by invalid state JSON.",
-          "Clear optional state or provide valid JSON before mounting."
-        );
-        return false;
-      }
-    }
-  }
+  const hasStateInput = refs.stateInput instanceof HTMLTextAreaElement
+    && Boolean(refs.stateInput.value.trim());
   updateSwitchMeta();
   updateStandaloneHref(toolId);
   writeQueryToolId(toolId, source === "init");
-  const previousMount = runtime.getCurrentMount();
-  const launchParams = readForwardedToolLaunchParams();
-  const mountResult = runtime.mountTool(toolId, {
-    source,
-    requestedAt: new Date().toISOString(),
-    sharedContext: {
-      requestedToolId: toolId,
-      previousToolId: previousMount?.tool?.id || "",
-      switchPosition: `${Math.max(1, getSelectedToolIndex() + 1)}/${Math.max(1, toolIds.length)}`
-    },
-    state: optionalState,
-    launchParams
-  });
+  const explicitToolPayloadById = workspaceManifestToolDiagnostics?.explicitToolPayloadById instanceof Map
+    ? workspaceManifestToolDiagnostics.explicitToolPayloadById
+    : null;
+  const payloadJson = explicitToolPayloadById ? (explicitToolPayloadById.get(toolId) || null) : null;
+  if (!payloadJson || typeof payloadJson !== "object" || Array.isArray(payloadJson)) {
+    writeStatus(`Launch blocked for ${toolId}: explicit payloadJson is required.`);
+    renderMountDiagnostic(
+      `Launch blocked for ${toolId}.`,
+      "Workspace Manager now enforces explicit launch(toolId, payloadJson, paletteJson?) inputs."
+    );
+    syncControlState();
+    return false;
+  }
+  if (hasStateInput) {
+    writeStatus("State JSON is ignored for explicit launch signature enforcement.");
+  }
+  const paletteJson = workspaceManifestToolDiagnostics?.explicitPalettePayload || null;
+  const mountResult = runtime.launch(toolId, payloadJson, paletteJson);
   if (!mountResult || !(mountResult.frame instanceof HTMLIFrameElement)) {
     const selectedEntry = getToolHostEntryById(manifest, toolId);
     const displayName = selectedEntry ? selectedEntry.displayName : toolId;