unraid-docker-manager/.planning/phases/16-api-migration/16-VERIFICATION.md

phase, verified, status, score, gaps, human_verification

phase	verified	status	score	gaps	human_verification
16-api-migration	2026-02-09T16:45:00Z	gaps_found	3/6	truth status reason artifacts missing User can start, stop, restart containers via Unraid API partial Inline keyboard actions work via GraphQL sub-workflows, but text commands (start/stop/restart <container>) still use Docker socket proxy Execute Command nodes path issue n8n-workflow.json 3 active Execute Command nodes with docker-socket-proxy references (Docker List for Action, Docker List for Update, Get Containers for Batch) Migrate 'start/stop/restart <container>' text command path to use GraphQL (Parse Action Command → Query Containers → n8n-actions.json) Migrate 'update <container>' text command path to use GraphQL (Parse Update Command → Query Container → n8n-update.json) Migrate 'batch' text command path to use GraphQL (Is Batch Command → Query Containers → n8n-batch-ui.json) truth status reason artifacts missing User can update single container via Unraid API partial Inline keyboard update button and sub-workflow work via GraphQL, but text command 'update <container>' still uses Docker socket proxy path issue n8n-workflow.json Docker List for Update Execute Command node active (handles 'update <container>' text command) Migrate 'update <container>' text command to use GraphQL query + n8n-update.json sub-workflow call truth status reason artifacts missing User can batch update multiple containers via Unraid API partial Batch selection UI and update execution work via GraphQL, but 'batch' text command entry point uses Docker socket proxy path issue n8n-workflow.json Get Containers for Batch Execute Command node active (handles 'batch' text command) Migrate 'batch' text command to use GraphQL query + n8n-batch-ui.json sub-workflow call	test expected why_human Send 'start plex' text command via Telegram Bot should respond with success/failure message Need to verify text command path behavior (currently uses Docker proxy, not GraphQL) test expected why_human Send 'update sonarr' text command via Telegram Bot should update container and respond with version change message Need to verify text command update path behavior (currently uses Docker proxy) test expected why_human Use inline keyboard 'Start' button on stopped container Container starts, bot shows success message Visual confirmation that GraphQL path works end-to-end test expected why_human Use inline keyboard 'Update' button on container with available update Container updates, bot shows 'updated: old -> new' message, Unraid Docker tab update badge disappears Visual confirmation of GraphQL updateContainer + automatic badge clearing test expected why_human Execute 'update all' with 3 containers Batch completes in 5-10 seconds with success message Verify parallel updateContainers mutation works (batch <=5) test expected why_human Execute 'update all' with 10 containers Serial updates with per-container progress messages Verify hybrid batch logic (batch >5 uses serial path)

Phase 16: API Migration Verification Report

Phase Goal: All container operations work via Unraid GraphQL API

Verified: 2026-02-09T16:45:00Z

Status: GAPS_FOUND

Re-verification: No — initial verification

Goal Achievement

Observable Truths

#	Truth	Status	Evidence
1	User can view container status via Unraid API (same UX as before)	✓ VERIFIED	n8n-status.json: 3/3 queries migrated to GraphQL, zero docker-socket-proxy refs, sub-workflow called 4x from main workflow
2	User can start, stop, restart containers via Unraid API	⚠ PARTIAL	n8n-actions.json fully migrated (5/5 GraphQL mutations), BUT text commands (start plex, stop sonarr) still use Docker proxy Execute Command nodes in main workflow
3	User can update single container via Unraid API (single mutation replaces 5-step Docker flow)	⚠ PARTIAL	n8n-update.json fully migrated (updateContainer mutation, 60s timeout), BUT update <container> text command uses Docker proxy Execute Command in main workflow
4	User can batch update multiple containers via Unraid API	⚠ PARTIAL	n8n-batch-ui.json fully migrated (5/5 GraphQL queries), hybrid updateContainers mutation wired, BUT batch text command entry uses Docker proxy Execute Command
5	User can "update all :latest" via Unraid API	✓ VERIFIED	Hybrid batch update: <=5 containers use parallel updateContainers mutation (120s timeout), >5 use serial sub-workflow calls. Zero Docker proxy refs in update-all path
6	Unraid update badges clear automatically after bot-initiated updates (no manual sync)	✓ VERIFIED	updateContainer mutation handles badge clearing (Unraid 7.2+), verified in n8n-update.json implementation

Score: 3/6 truths fully verified, 3/6 partial (sub-workflows migrated, main workflow text commands not migrated)

Required Artifacts

Artifact	Expected	Status	Details
n8n-status.json	Container status queries via GraphQL	✓ VERIFIED	17 nodes, 3 GraphQL HTTP Request nodes, 3 normalizers, 3 registry updates, zero docker-socket-proxy refs
n8n-actions.json	Lifecycle mutations via GraphQL	✓ VERIFIED	21 nodes, 5 GraphQL HTTP Request nodes (query + start/stop mutations + restart chain), 1 normalizer, zero docker-socket-proxy refs
n8n-update.json	Single updateContainer mutation	✓ VERIFIED	29 nodes (reduced from 34), 3 GraphQL HTTP nodes (2 queries + 1 mutation), 60s timeout, zero docker-socket-proxy refs
n8n-batch-ui.json	Batch selection queries via GraphQL	✓ VERIFIED	22 nodes, 5 GraphQL HTTP Request nodes, 5 normalizers, zero docker-socket-proxy refs
n8n-workflow.json	Main workflow with GraphQL queries	⚠ PARTIAL	193 nodes, 9 GraphQL HTTP nodes, 7 normalizers, 7 registry updates, BUT 3 active Execute Command nodes with docker-socket-proxy refs (Docker List for Action, Docker List for Update, Get Containers for Batch)

Key Link Verification

From	To	Via	Status	Details
n8n-status.json HTTP nodes	Unraid GraphQL API	POST to $env.UNRAID_HOST/graphql	✓ WIRED	3 container queries, 15s timeout, Header Auth credential
n8n-actions.json HTTP nodes	Unraid GraphQL API	POST mutations (start, stop, restart chain)	✓ WIRED	5 mutations, ALREADY_IN_STATE mapped to statusCode 304
n8n-update.json HTTP node	Unraid GraphQL API	POST updateContainer mutation	✓ WIRED	60s timeout, ImageId comparison for update detection
n8n-batch-ui.json HTTP nodes	Unraid GraphQL API	POST container queries	✓ WIRED	5 queries (mode/toggle/exec/nav/clear paths)
Main workflow GraphQL nodes	Unraid GraphQL API	POST queries/mutations	✓ WIRED	9 GraphQL nodes active (6 queries + hybrid batch mutation)
Main workflow Execute Workflow nodes	Sub-workflows	n8n-actions.json, n8n-update.json, n8n-status.json, n8n-batch-ui.json	✓ WIRED	17 Execute Workflow nodes, all sub-workflows integrated
Container ID Registry	Sub-workflow mutations	Name→PrefixedID mapping in static data	✓ WIRED	Updated after every GraphQL query, used by all mutations
Text command paths	Docker socket proxy	Execute Command nodes	✗ UNWIRED (should use GraphQL)	3 active nodes: Docker List for Action, Docker List for Update, Get Containers for Batch

Requirements Coverage

Phase 16 maps to 8 requirements (API-01 through API-08):

Requirement	Status	Blocking Issue
API-01: Container status query via GraphQL	✓ SATISFIED	n8n-status.json fully migrated
API-02: Container start via GraphQL	⚠ PARTIAL	n8n-actions.json migrated, text command path not migrated
API-03: Container stop via GraphQL	⚠ PARTIAL	n8n-actions.json migrated, text command path not migrated
API-04: Container restart via GraphQL (stop+start)	⚠ PARTIAL	n8n-actions.json migrated, text command path not migrated
API-05: Single updateContainer mutation	⚠ PARTIAL	n8n-update.json migrated, text command path not migrated
API-06: Batch updateContainers mutation	⚠ PARTIAL	n8n-batch-ui.json + hybrid mutation migrated, text command entry not migrated
API-07: "Update all :latest" via GraphQL	✓ SATISFIED	Hybrid batch update fully migrated (parallel/serial paths)
API-08: Unraid update badges clear automatically	✓ SATISFIED	updateContainer mutation inherent behavior (Unraid 7.2+)

Coverage: 3/8 fully satisfied, 5/8 partial (sub-workflows complete, main workflow text commands incomplete)

Anti-Patterns Found

File	Line	Pattern	Severity	Impact
n8n-workflow.json	420	Execute Command with docker-socket-proxy curl	🛑 Blocker	Text command start/stop/restart <container> uses Docker API, not GraphQL
n8n-workflow.json	1301	Execute Command with docker-socket-proxy curl	🛑 Blocker	Text command update <container> uses Docker API, not GraphQL
n8n-workflow.json	2133	Execute Command with docker-socket-proxy curl	🛑 Blocker	Text command batch uses Docker API, not GraphQL
n8n-workflow.json	434, 1845, 3093	Code nodes with docker-socket-proxy in comments/strings	⚠ Warning	Stale references in comments (not functional, but misleading)
n8n-workflow.json	-	2 dead code nodes (Build Action Command, Build Immediate Action Command)	ℹ Info	No incoming connections, safe to delete

Human Verification Required

See frontmatter human_verification section for 6 manual test cases:

1. Text command 'start plex' — Verify Docker proxy path still works (until migrated)
2. Text command 'update sonarr' — Verify Docker proxy update path still works
3. Inline keyboard 'Start' button — Verify GraphQL path works end-to-end
4. Inline keyboard 'Update' button — Verify GraphQL updateContainer + badge clearing
5. 'update all' with 3 containers — Verify parallel updateContainers mutation (<= 5 batch)
6. 'update all' with 10 containers — Verify serial sub-workflow path (>5 batch)

Gaps Summary

What was achieved:

All 5 sub-workflows (n8n-status.json, n8n-actions.json, n8n-update.json, n8n-batch-ui.json, and portions of n8n-workflow.json) successfully migrated to Unraid GraphQL API. Inline keyboard interactions (the primary UX) work entirely via GraphQL. Update-all batch operations use the hybrid updateContainers pattern for efficiency.

What's missing:

The 3 text command entry points in the main workflow still use Docker socket proxy Execute Command nodes:

1. start/stop/restart <container> text commands → Should query containers via GraphQL, then call n8n-actions.json sub-workflow (like inline keyboard path does)
2. update <container> text command → Should query containers via GraphQL, then call n8n-update.json sub-workflow
3. batch text command → Should query containers via GraphQL, then call n8n-batch-ui.json sub-workflow

These 3 nodes are actively wired (not dead code) and handle user interactions. The phase goal "All container operations work via Unraid GraphQL API" is not achieved until these text command paths are migrated.

Why this matters:

The Docker socket proxy cannot be safely removed (Phase 17 goal) until these 3 text command paths are migrated. Users can trigger Docker API calls via text commands, maintaining the dual-API architecture the phase intended to eliminate.

Recommended fix:

Create a follow-up plan (16-06) to migrate the 3 text command paths:

• Replace Execute Command nodes with GraphQL HTTP Request + Normalizer + Registry Update
• Wire to existing sub-workflow Execute Workflow nodes (reuse n8n-actions.json, n8n-update.json, n8n-batch-ui.json)
• Remove Execute Command nodes and 2 dead code nodes (Build Action Command, Build Immediate Action Command)
• Verify zero Docker socket proxy references across all workflows

---

Verified: 2026-02-09T16:45:00Z

Verifier: Claude (gsd-verifier)