@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

package/dist/resources/extensions/claude-code-cli/turn-assembler.js

@@ -0,0 +1,224 @@
+// gsd-pi - Claude Code logical turn assembly
+import { PartialMessageBuilder } from "./partial-builder.js";
+/** Normalise heterogeneous SDK tool-result content (string, array, or object) into a uniform `ExternalToolResultContentBlock[]`. */
+function normalizeToolResultContent(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (!Array.isArray(content)) {
+        if (content == null)
+            return [{ type: "text", text: "" }];
+        return [{ type: "text", text: JSON.stringify(content) }];
+    }
+    const blocks = [];
+    for (const item of content) {
+        if (typeof item === "string") {
+            blocks.push({ type: "text", text: item });
+            continue;
+        }
+        if (!item || typeof item !== "object") {
+            blocks.push({ type: "text", text: String(item) });
+            continue;
+        }
+        const block = item;
+        if (block.type === "text") {
+            blocks.push({ type: "text", text: typeof block.text === "string" ? block.text : "" });
+            continue;
+        }
+        if (block.type === "image"
+            && typeof block.data === "string"
+            && typeof block.mimeType === "string") {
+            blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
+            continue;
+        }
+        blocks.push({ type: "text", text: JSON.stringify(block) });
+    }
+    return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
+}
+/**
+ * Extract a `details` payload from an MCP tool-result block.
+ *
+ * MCP's `CallToolResult` carries structured data in `structuredContent` — the
+ * protocol's supported channel for non-text payloads. Claude Code's synthetic
+ * user message may surface that field in one of two shapes depending on SDK
+ * version: as a sibling on the `mcp_tool_result` block itself, or as a
+ * dedicated content sub-block with `type: "structuredContent"`. Snake-case
+ * (`structured_content`) is accepted defensively in case a transport hop
+ * rewrites casing. All other shapes return undefined, matching the nullable
+ * `details` contract consumed by tool result renderers.
+ */
+function extractStructuredDetailsFromBlock(block) {
+    const sibling = block.structuredContent ?? block.structured_content;
+    if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
+        return sibling;
+    }
+    if (Array.isArray(block.content)) {
+        for (const item of block.content) {
+            if (!item || typeof item !== "object")
+                continue;
+            const sub = item;
+            if (sub.type !== "structuredContent" && sub.type !== "structured_content")
+                continue;
+            const payload = sub.structuredContent ?? sub.structured_content ?? sub.data ?? sub.value;
+            if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                return payload;
+            }
+        }
+    }
+    // Return undefined (not {}) when no structured payload is present, matching
+    // the pre-#4477 contract where `details` was nullable. An empty-object
+    // sentinel is truthy and breaks downstream consumers that gate on
+    // `if (details)`. `undefined` matches the type of the field these results
+    // flow into (`Record<string, unknown> | undefined`).
+    return undefined;
+}
+/**
+ * True for items that are MCP `structuredContent` pseudo-blocks living inside
+ * a tool-result `content[]` array. These blocks carry the structured payload
+ * (extracted separately by `extractStructuredDetailsFromBlock`) and must NOT
+ * leak into the visible content rendered to the user — otherwise the renderer
+ * stringifies the JSON pseudo-block and shows it next to the actual tool
+ * output. See PR #4477 review (post-fix-round).
+ */
+function isStructuredContentPseudoBlock(item) {
+    if (!item || typeof item !== "object")
+        return false;
+    const type = item.type;
+    return type === "structuredContent" || type === "structured_content";
+}
+/**
+ * Strip `structuredContent` pseudo-blocks from a tool-result content array
+ * before normalization. The structured payload is extracted via the sibling
+ * `structuredContent` field (or a dedicated extractor pass on the raw block);
+ * the visible content path must not include the pseudo-block itself.
+ */
+function stripStructuredContentPseudoBlocks(content) {
+    if (!Array.isArray(content))
+        return content;
+    return content.filter((item) => !isStructuredContentPseudoBlock(item));
+}
+/** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
+export function extractToolResultsFromSdkUserMessage(message) {
+    const extracted = [];
+    const seen = new Set();
+    const rawMessage = message.message;
+    const content = Array.isArray(rawMessage?.content) ? rawMessage.content : [];
+    for (const item of content) {
+        if (!item || typeof item !== "object")
+            continue;
+        const block = item;
+        const type = typeof block.type === "string" ? block.type : "";
+        if (type !== "tool_result" && type !== "mcp_tool_result")
+            continue;
+        const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : "";
+        if (!toolUseId || seen.has(toolUseId))
+            continue;
+        seen.add(toolUseId);
+        extracted.push({
+            toolUseId,
+            result: {
+                content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(block.content)),
+                details: extractStructuredDetailsFromBlock(block),
+                isError: block.is_error === true,
+            },
+        });
+    }
+    if (extracted.length === 0) {
+        const fallback = message.tool_use_result;
+        if (fallback && typeof fallback === "object") {
+            const toolResult = fallback;
+            const toolUseId = typeof toolResult.tool_use_id === "string" ? toolResult.tool_use_id : "";
+            if (toolUseId) {
+                extracted.push({
+                    toolUseId,
+                    result: {
+                        content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(toolResult.content)),
+                        details: extractStructuredDetailsFromBlock(toolResult),
+                        isError: toolResult.is_error === true,
+                    },
+                });
+            }
+        }
+    }
+    return extracted;
+}
+/** Attach external tool results from the SDK synthetic user message to their corresponding tool-call blocks by ID. */
+export function attachExternalResultsToToolBlocks(toolBlocks, toolResultsById) {
+    for (const block of toolBlocks) {
+        if (block.type !== "toolCall" && block.type !== "serverToolUse")
+            continue;
+        const externalResult = toolResultsById.get(block.id);
+        if (!externalResult)
+            continue;
+        block.externalResult = externalResult;
+    }
+}
+/**
+ * Build the final assistant content that Agent Core consumes in
+ * `externalToolExecution` mode. This preserves tool-call blocks, attaches any
+ * SDK-produced external results by tool-call id, and then appends the final
+ * text/thinking blocks for the completed turn.
+ */
+export function buildFinalAssistantContent(params) {
+    const mergedToolBlocks = [...params.intermediateToolBlocks];
+    if (params.pendingContent) {
+        mergePendingToolCalls(mergedToolBlocks, params.pendingContent);
+    }
+    attachExternalResultsToToolBlocks(mergedToolBlocks, params.toolResultsById);
+    const finalContent = [...mergedToolBlocks];
+    if (params.pendingContent && params.pendingContent.length > 0) {
+        for (const block of params.pendingContent) {
+            if (block.type === "text" || block.type === "thinking") {
+                finalContent.push(block);
+            }
+        }
+    }
+    else {
+        if (params.lastThinkingContent) {
+            finalContent.push({ type: "thinking", thinking: params.lastThinkingContent });
+        }
+        if (params.lastTextContent) {
+            finalContent.push({ type: "text", text: params.lastTextContent });
+        }
+    }
+    if (finalContent.length === 0 && params.fallbackResultText) {
+        finalContent.push({ type: "text", text: params.fallbackResultText });
+    }
+    return finalContent;
+}
+/**
+ * Merge tool-call blocks from the active partial-message builder into the
+ * running list of intermediate tool calls, preserving order and de-duping
+ * by tool-call id. Exposed for testing the F3 fix (final-turn tool calls
+ * dropped when `result` arrives without a preceding synthetic `user`).
+ */
+export function mergePendingToolCalls(intermediate, pending) {
+    const alreadyIncluded = new Set();
+    for (const block of intermediate) {
+        if (block.type === "toolCall")
+            alreadyIncluded.add(block.id);
+    }
+    for (const block of pending) {
+        if (block.type !== "toolCall")
+            continue;
+        if (alreadyIncluded.has(block.id))
+            continue;
+        alreadyIncluded.add(block.id);
+        intermediate.push(block);
+    }
+    return intermediate;
+}
+export function handleClaudeCodePartialStreamEvent(builder, event, modelId) {
+    if (event.type === "message_start") {
+        // Claude Code can emit repeated SDK message_start events inside one
+        // logical assistant response. Keep appending until a synthetic user
+        // tool-result boundary explicitly clears the builder.
+        return {
+            builder: builder ?? new PartialMessageBuilder(event.message?.model ?? modelId),
+            assistantEvent: null,
+        };
+    }
+    if (!builder)
+        return { builder, assistantEvent: null };
+    return { builder, assistantEvent: builder.handleEvent(event) };
+}

package/dist/resources/extensions/github-sync/templates.js

@@ -7,7 +7,7 @@
  * All functions produce GitHub-flavored markdown strings ready
  * for the `gh` CLI body parameters.
  */
-import { buildPrEvidence } from "../gsd/pr-evidence.js";
+import { buildPullRequestEvidence } from "../gsd/pull-request-process.js";
 // ─── Helpers ────────────────────────────────────────────────────────────────
 /**
  * Wrap a string in a CommonMark inline-code span, escaping any embedded
@@ -85,7 +85,7 @@ export function formatSlicePRBody(data) {
         .map((task) => task.issueNumber)
         .filter((issueNumber) => typeof issueNumber === "number")
         .map((issueNumber) => `#${issueNumber}`);
-    return buildPrEvidence({
+    return buildPullRequestEvidence({
         milestoneId: data.id,
         subjectId: data.id,
         subjectKind: "slice",
@@ -172,7 +172,7 @@ export function formatSwarmLanePRBody(data) {
         `### Changed contracts\n${checkedList(data.lane.changedContracts, "No shared contracts changed").join("\n")}`,
         `### Transition risks\n${checkedList(data.transitionRisks, "No transition risks identified").join("\n")}`,
     ].filter(Boolean);
-    return buildPrEvidence({
+    return buildPullRequestEvidence({
         milestoneId: laneLabel,
         subjectId: laneLabel,
         subjectKind: "workflow",

package/dist/resources/extensions/gsd/artifact-projection.js

@@ -0,0 +1,14 @@
+// Project/App: gsd-pi
+// File Purpose: Resolves closeout artifact projection roots across project and milestone worktrees.
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+export function resolveCloseoutArtifactProjection(input) {
+    const projectRoot = resolveWorktreeProjectRoot(input.basePath, input.originalBasePath);
+    const canonicalMilestoneRoot = resolveCanonicalMilestoneRoot(projectRoot, input.milestoneId);
+    return {
+        projectRoot,
+        canonicalMilestoneRoot,
+        summaryArtifactBasePath: canonicalMilestoneRoot,
+        gateEvidenceBasePath: canonicalMilestoneRoot,
+    };
+}

package/dist/resources/extensions/gsd/auto/contracts.js

@@ -1,3 +1,10 @@
 // Project/App: gsd-pi
-// File Purpose: Auto Orchestration module interfaces and ADR-015 invariant adapter contracts.
+// File Purpose: Auto Orchestration module public contract types.
+//
+// Phase 2 of #442 collapsed the nine single-implementation adapter interfaces
+// (DispatchAdapter, RecoveryAdapter, StateReconciliationAdapter,
+// ToolContractAdapter, WorktreeAdapter, HealthAdapter, UokGateAdapter,
+// RuntimePersistenceAdapter, NotificationAdapter) and AutoOrchestratorDeps
+// into AutoOrchestrator itself (auto/orchestrator.ts). Only the public result
+// and lifecycle-interface types remain here.
 export {};

package/dist/resources/extensions/gsd/auto/custom-verify-retry-store.js

@@ -4,6 +4,12 @@ import { readFileSync, mkdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteSync } from "../atomic-write.js";
 import { gsdRoot } from "../paths.js";
+function ensureExhaustedVerificationUnits(s) {
+    if (!s.exhaustedVerificationUnits) {
+        s.exhaustedVerificationUnits = new Set();
+    }
+    return s.exhaustedVerificationUnits;
+}
 export function customVerifyRetryStateDir(s) {
     return s.activeRunDir ? join(s.activeRunDir, "runtime") : join(gsdRoot(s.basePath), "runtime");
 }
@@ -11,7 +17,8 @@ export function customVerifyRetryStatePath(s) {
     return join(customVerifyRetryStateDir(s), "custom-verify-retries.json");
 }
 export function hydrateCustomVerifyRetryCounts(s, deps) {
-    if (s.verificationRetryCount.size > 0) {
+    const exhaustedUnits = ensureExhaustedVerificationUnits(s);
+    if (s.verificationRetryCount.size > 0 || exhaustedUnits.size > 0) {
         return s.verificationRetryCount;
     }
     try {
@@ -24,6 +31,12 @@ export function hydrateCustomVerifyRetryCounts(s, deps) {
                 s.verificationRetryCount.set(key, Math.floor(value));
             }
         }
+        const exhausted = raw && typeof raw === "object" && Array.isArray(raw.exhausted) ? raw.exhausted : [];
+        for (const key of exhausted) {
+            if (typeof key === "string" && key.length > 0) {
+                exhaustedUnits.add(key);
+            }
+        }
     }
     catch (err) {
         deps.logFailure(err);
@@ -32,15 +45,17 @@ export function hydrateCustomVerifyRetryCounts(s, deps) {
 }
 export function saveCustomVerifyRetryCounts(s, deps) {
     const retryCounts = s.verificationRetryCount;
+    const exhaustedUnits = ensureExhaustedVerificationUnits(s);
     const filePath = customVerifyRetryStatePath(s);
     try {
-        if (!retryCounts || retryCounts.size === 0) {
+        if ((!retryCounts || retryCounts.size === 0) && (!exhaustedUnits || exhaustedUnits.size === 0)) {
             unlinkSync(filePath);
             return;
         }
         mkdirSync(customVerifyRetryStateDir(s), { recursive: true });
         atomicWriteSync(filePath, JSON.stringify({
             counts: Object.fromEntries(retryCounts),
+            exhausted: [...exhaustedUnits],
             updatedAt: new Date().toISOString(),
         }) + "\n");
     }

package/dist/resources/extensions/gsd/auto/detect-stuck.js

@@ -3,6 +3,7 @@
  *
  * Leaf node in the import DAG.
  */
+import { parseDispatchKey } from "./dispatch-key.js";
 import { summarizeLogs } from "../workflow-logger.js";
 import { getLatestForUnit } from "../db/unit-dispatches.js";
 /**
@@ -11,6 +12,18 @@ import { getLatestForUnit } from "../db/unit-dispatches.js";
  * and similar Node.js filesystem error messages.
  */
 const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
+function rowInsideRetryBudget(row) {
+    if (!row)
+        return false;
+    if (row.attempt_n >= row.max_attempts)
+        return false;
+    if (!row.next_run_at)
+        return false;
+    const nextRun = Date.parse(row.next_run_at);
+    if (!Number.isFinite(nextRun))
+        return false;
+    return nextRun > Date.now();
+}
 /**
  * Phase B / codex review MEDIUM B3 — retry coupling.
  *
@@ -20,23 +33,26 @@ const ENOENT_PATH_RE = /ENOENT[^']*'([^']+)'/;
  * waiting on its own backoff. Suppress the stuck verdict in that case so
  * the retry budget can fully drain before we declare stuck.
  *
+ * Window keys are compound (`unitType:unitId`, legacy `unitType/unitId`)
+ * while the production dispatch ledger keys rows by the bare unit id with
+ * the unit type in its own column. Look the bare unit id up first (with a
+ * unit_type match — the production shape), then fall back to the full
+ * compound key (test fixtures / legacy rows).
+ *
  * Returns true if the dispatch ledger says we should suppress the stuck
  * signal; false (no suppression) when the ledger is unavailable or has
  * no opinion.
  */
 function retryBudgetSuppresses(unitKey) {
     try {
-        const latest = getLatestForUnit(unitKey);
-        if (!latest)
-            return false;
-        if (latest.attempt_n >= latest.max_attempts)
-            return false;
-        if (!latest.next_run_at)
-            return false;
-        const nextRun = Date.parse(latest.next_run_at);
-        if (!Number.isFinite(nextRun))
-            return false;
-        return nextRun > Date.now();
+        const parsed = parseDispatchKey(unitKey);
+        if (parsed) {
+            const bare = getLatestForUnit(parsed.unitId);
+            if (bare && bare.unit_type === parsed.unitType && rowInsideRetryBudget(bare)) {
+                return true;
+            }
+        }
+        return rowInsideRetryBudget(getLatestForUnit(unitKey));
     }
     catch {
         return false;
@@ -66,6 +82,10 @@ export function detectStuck(window, _retryContext) {
     const suffix = loggerSummary ? ` — ${loggerSummary}` : "";
     const last = window[window.length - 1];
     const prev = window[window.length - 2];
+    // Rules 2 and 2b share one retry-budget verdict for `last.key` — compute it
+    // at most once per invocation (it hits the dispatch ledger).
+    let suppressionVerdict;
+    const suppressed = () => (suppressionVerdict ??= retryBudgetSuppresses(last.key));
     // Rule 1: Same error repeated consecutively
     if (last.error && prev.error && last.error === prev.error) {
         return {
@@ -77,7 +97,7 @@ export function detectStuck(window, _retryContext) {
     // says we're inside the retry-backoff window (codex MEDIUM B3).
     if (window.length >= 3) {
         const lastThree = window.slice(-3);
-        if (lastThree.every((u) => u.key === last.key) && !retryBudgetSuppresses(last.key)) {
+        if (lastThree.every((u) => u.key === last.key) && !suppressed()) {
             return {
                 stuck: true,
                 reason: `${last.key} derived 3 consecutive times without progress${suffix}`,
@@ -87,7 +107,7 @@ export function detectStuck(window, _retryContext) {
     // Rule 2b: Same unit key 3+ times anywhere in the active window — same
     // retry-budget suppression as Rule 2.
     const countInWindow = window.filter((entry) => entry.key === last.key).length;
-    if (countInWindow >= 3 && !retryBudgetSuppresses(last.key)) {
+    if (countInWindow >= 3 && !suppressed()) {
         return {
             stuck: true,
             reason: `${last.key} derived ${countInWindow} times in last ${window.length} attempts without progress${suffix}`,

package/dist/resources/extensions/gsd/auto/dispatch-history.js

@@ -0,0 +1,105 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch History module — the single home for the auto
+// orchestrator's dispatch-decision window, cross-session rehydration, and
+// stuck detection (#482 / #442 deepening).
+/**
+ * auto/dispatch-history.ts — Dispatch History module.
+ *
+ * Owns the sliding window of recent dispatch decisions that the Auto
+ * Orchestration module consults for idempotency and stuck-loop detection.
+ *
+ * Before this module existed the orchestrator kept a private in-memory
+ * `dispatchKeyWindow: string[]` that was reset to `[]` in start()/resume().
+ * Because a fresh orchestrator is constructed per session, the window never
+ * saw dispatches from a previous session — a unit could be re-dispatched
+ * across session restarts indefinitely (issue #482: 146 re-dispatches of the
+ * same unit). This module rehydrates the window from the DB dispatch ledger
+ * (`unit_dispatches`, via getRecentUnitKeysForProjectRoot) so stuck detection
+ * survives process restarts, and it delegates the verdict to the full
+ * detect-stuck rule set (repeat-error / consecutive / oscillation / ENOENT,
+ * with retry-budget suppression) instead of the bare saturation count.
+ *
+ * Key format: the canonical dispatch key is `${unitType}:${unitId}`
+ * (e.g. "execute-task:M001/S01/T01"). The legacy auto/phases.ts path and the
+ * DB rehydration helper use `${unitType}/${unitId}`; normalizeDispatchKey
+ * converts those on rehydrate so one format lives in the window. The key
+ * grammar itself lives in auto/dispatch-key.ts and is re-exported here for
+ * import stability.
+ */
+import { buildDispatchKey, normalizeDispatchKey } from "./dispatch-key.js";
+import { detectStuck } from "./detect-stuck.js";
+import { getLatestForUnit, getRecentUnitKeysForProjectRoot, } from "../db/unit-dispatches.js";
+import { debugLog } from "../debug-logger.js";
+export { buildDispatchKey, normalizeDispatchKey, parseDispatchKey } from "./dispatch-key.js";
+/**
+ * Size of the dispatch-decision ring buffer. Mirrors the legacy
+ * `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is preserved across the
+ * cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
+function lookupLatestLedgerError(unitType, unitId) {
+    try {
+        const row = getLatestForUnit(unitId);
+        // The ledger keys rows by bare unit id; require a unit_type match so
+        // another unit type's error on the same id is never attached (it would
+        // trip the repeat-error rule spuriously).
+        if (!row || row.unit_type !== unitType)
+            return undefined;
+        return row.error_summary ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createDispatchHistory(options) {
+    const windowSize = options.windowSize ?? STUCK_WINDOW_SIZE;
+    let window = [];
+    return {
+        recordDispatch(unitType, unitId) {
+            const key = buildDispatchKey(unitType, unitId);
+            // Ledger errors only feed the repeat-error/ENOENT rules, which need a
+            // prior occurrence of the same unit in the window — first-dispatch
+            // advances (the common case) pay zero DB cost.
+            const error = window.some((entry) => entry.key === key)
+                ? lookupLatestLedgerError(unitType, unitId)
+                : undefined;
+            window.push({ key, error });
+            while (window.length > windowSize)
+                window.shift();
+            return key;
+        },
+        getRecentWindow() {
+            return window;
+        },
+        countMatching(key) {
+            return window.filter((entry) => entry.key === key).length;
+        },
+        detectStuck() {
+            return detectStuck(window);
+        },
+        rehydrate() {
+            const scopeId = options.resolveScopeId();
+            if (!scopeId)
+                return 0;
+            try {
+                const persisted = getRecentUnitKeysForProjectRoot(scopeId, windowSize);
+                if (persisted.length === 0)
+                    return 0;
+                window = persisted.map(({ key }) => ({ key: normalizeDispatchKey(key) }));
+                while (window.length > windowSize)
+                    window.shift();
+                return window.length;
+            }
+            catch (err) {
+                debugLog("dispatchHistory", {
+                    phase: "rehydrate-failed",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return 0;
+            }
+        },
+        clearOnRecovery() {
+            window = [];
+        },
+    };
+}

package/dist/resources/extensions/gsd/auto/dispatch-key.js

@@ -0,0 +1,37 @@
+// Project/App: gsd-pi
+// File Purpose: Dispatch-key grammar — the single home for building, parsing,
+// and normalizing the auto orchestrator's dispatch keys.
+/**
+ * auto/dispatch-key.ts — Dispatch-key grammar.
+ *
+ * Canonical key: `${unitType}:${unitId}` (e.g. "execute-task:M001/S01/T01").
+ * Legacy key: `${unitType}/${unitId}` (auto/phases.ts, DB rehydration). Unit
+ * ids themselves contain "/" (M001/S01/T01) — the first segment is the unit
+ * type.
+ *
+ * Leaf node in the import DAG: both dispatch-history.ts and detect-stuck.ts
+ * consume this grammar, so it lives below them.
+ */
+/** Build the canonical dispatch key for a unit. One format, one home. */
+export function buildDispatchKey(unitType, unitId) {
+    return `${unitType}:${unitId}`;
+}
+/** Split a canonical or legacy dispatch key into its unit type and id. */
+export function parseDispatchKey(key) {
+    const colon = key.indexOf(":");
+    if (colon > 0) {
+        return { unitType: key.slice(0, colon), unitId: key.slice(colon + 1) };
+    }
+    const slash = key.indexOf("/");
+    if (slash > 0) {
+        return { unitType: key.slice(0, slash), unitId: key.slice(slash + 1) };
+    }
+    return null;
+}
+/** Normalize a legacy `${unitType}/${unitId}` key to the canonical format. */
+export function normalizeDispatchKey(key) {
+    if (key.includes(":"))
+        return key;
+    const parsed = parseDispatchKey(key);
+    return parsed ? buildDispatchKey(parsed.unitType, parsed.unitId) : key;
+}